analysis Package

analysis Package

This package is an overarching package for modules performing various analyses of materials data.

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)

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.

Args:

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.

get_oxi_state_decorated_structure(structure)

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

Args:

structure:

Structure to analyze

Returns:

A modified structure that is oxidation state decorated.

Raises:

A ValueError is the valences cannot be determined.

get_valences(structure)

Returns a list of valences for the structure. This currently works only for ordered structures only.

Args:

structure:

Structure to analyze

Returns:

A list of valences for each site in the structure, e.g., [1, 1, -2].

Raises:

A ValueError is the valences cannot be determined.

calculate_bv_sum(site, nn_list, scale_factor=1)

Calculates the BV sum of a site.

Args:

site:

The site

nn_list:

List of nearest neighbors in the format [(nn_site, dist), ...].

anion_el:

The most electronegative element in the structure.

scale_factor:

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

diffusion_analyzer Module

A module to perform diffusion analyses (e.g. calculating diffusivity from mean square displacements etc.). If you use this module, please consider citing the following papers:

Ong, S. P., Mo, Y., Richards, W. D., Miara, L., Lee, H. S., & Ceder, G.
(2013). Phase stability, electrochemical stability and ionic conductivity
of the Li10+-1MP2X12 (M = Ge, Si, Sn, Al or P, and X = O, S or Se) family
of superionic conductors. Energy & Environmental Science, 6(1), 148.
doi:10.1039/c2ee23355j

Mo, Y., Ong, S. P., & Ceder, G. (2012). First Principles Study of the
Li10GeP2S12 Lithium Super Ionic Conductor Material. Chemistry of Materials,
24(1), 15-17. doi:10.1021/cm203303y

class DiffusionAnalyzer(structure, displacements, specie, temperature, time_step, step_skip=10, min_obs=30, weighted=True)

Bases: pymatgen.serializers.json_coders.MSONable

Class for performing diffusion analysis.

This constructor is meant to be used with pre-processed data. Other convenient constructors are provided as class methods (see from_vaspruns and from_files).

Given a matrix of displacements (see arguments below for expected format), the diffusivity is given by:

D = 1 / 2dt * <mean square displacement>

where d is the dimensionality, t is the time. To obtain a reliable diffusion estimate, a least squares regression of the MSD against time to obtain the slope, which is then related to the diffusivity.

Args:

structure:

Initial structure.

displacements:

Numpy array of with shape [site, time step, axis]

specie:

Specie to calculate diffusivity for as a String. E.g., “Li”.

temperature:

Temperature of the diffusion run in Kelvin.

time_step:

Time step between measurements.

step_skip:

Sampling frequency of the displacements (time_step is multiplied by this number to get the real time between measurements)

min_obs:

Minimum number of observations to have before including in the MSD vs dt calculation. E.g. If a structure has 10 diffusing atoms, and min_obs = 30, the MSD vs dt will be calculated up to dt = total_run_time / 3, so that each diffusing atom is measured at least 3 uncorrelated times.

weighted:

Uses a weighted least squares to fit the MSD vs dt. Weights are proportional to 1/dt, since the number of observations are also proportional to 1/dt (and hence the variance is proportional to dt)

classmethod from_dict(d)

classmethod from_files(filepaths, specie, step_skip=10, min_obs=30, weighted=True, ncores=None)

Convenient constructor that takes in a list of vasprun.xml paths to perform diffusion analysis.

Args:

filepaths:

List of paths to vasprun.xml files of runs. (must be ordered in sequence of run). For example, you may have done sequential VASP runs and they are in run1, run2, run3, etc. You should then pass in [“run1/vasprun.xml”, “run2/vasprun.xml”, ...].

specie:

Specie to calculate diffusivity for as a String. E.g., “Li”.

step_skip:

Sampling frequency of the displacements (time_step is multiplied by this number to get the real time between measurements). E.g., you may not want to sample every single time step.

min_obs:

Minimum number of observations to have before including in the MSD vs dt calculation. E.g. If a structure has 10 diffusing atoms, and min_obs = 30, the MSD vs dt will be calculated up to dt = total_run_time / 3, so that each diffusing atom is measured at least 3 uncorrelated times.

weighted:

Uses a weighted least squares to fit the MSD vs dt. Weights are proportional to 1/dt, since the number of observations are also proportional to 1/dt (and hence the variance is proportional to dt)

ncores:

Numbers of cores to use for multiprocessing. Can speed up vasprun parsing considerable. Defaults to None, which means serial.

classmethod from_vaspruns(vaspruns, specie, min_obs=30, weighted=True)

Convenient constructor that takes in a list of Vasprun objects to perform diffusion analysis.

Args:

vaspruns:

list of Vasprun objects (must be ordered in sequence of run).

E.g., you may have performed sequential VASP runs to obtain sufficient statistics.

specie:

Specie to calculate diffusivity for as a String. E.g., “Li”.

min_obs:

Minimum number of observations to have before including in the MSD vs dt calculation. E.g. If a structure has 10 diffusing atoms, and min_obs = 30, the MSD vs dt will be calculated up to dt = total_run_time / 3, so that each diffusing atom is measured at least 3 uncorrelated times.

weighted:

Uses a weighted least squares to fit the MSD vs dt. Weights are proportional to 1/dt, since the number of observations are also proportional to 1/dt (and hence the variance is proportional to dt)

plot_smoothed_msd()

Plot the smoothed msd vs time graph. Useful for checking convergence.

to_dict

get_arrhenius_plot(temps, diffusivites, **kwargs)

Returns an Arrhenius plot.

Args:

temps:

A sequence of temperatures.

diffusivities:

A sequence of diffusivities (e.g., from DiffusionAnalyzer .diffusivity).

**kwargs:

Any keyword args supported by matplotlib.pyplot.plot.

Returns:

A matplotlib.pyplot object. Do plt.show() to show the plot.

get_conversion_factor(structure, species, temperature)

Conversion factor to convert between cm^2/s diffusivity measurements and mS/cm conductivity measurements based on number of atoms of diffusing species. Note that the charge is based on the oxidation state of the species (where available), or else the number of valence electrons (usually a good guess, esp for main group ions).

Args:

structure:

Input structure.

species:

Diffusing species.

temperature:

Temperature of the diffusion run in Kelvin.

Returns:

Conversion factor. Conductivity (in mS/cm) = Conversion Factor * Diffusivity (in cm^2/s)

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)

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

Args:

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

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

ALGO_COMPLETE = 1

ALGO_FAST = 0

ALGO_TIME_LIMIT = 3

add_m_list(matrix_sum, m_list)

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)

Computes a best case given a matrix and manipulation list.

Args:

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.

best_m_list

get_next_index(matrix, manipulation, indices_left)

Returns an index that should have the most negative effect on the matrix sum

minimize_matrix()

This method finds and returns the permutations that produce the lowest ewald sum calls recursive function to iterate through permutations

minimized_sum

output_lists

class EwaldSummation(structure, real_space_cut=None, recip_space_cut=None, eta=None, acc_factor=8.0)

Bases: object

Calculates the electrostatic energy of a periodic array of charges using the Ewald technique. Ref: 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.

Args:

structure:

input structure that must have proper Specie on all sites, i.e. Element with oxidation state. Use StructureEditor.add_oxidation_state... in pymatgen.core.structure_modifier for example.

real_space_cut:

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:

Reciprocal space cutoff radius. Defaults to None, which means determine automagically using the formula given in gulp 3.1 documentation.

eta:

The screening parameter. Defaults to None, which means determine automatically.

acc_factor:

No. of significant figures each sum is converged to.

CONV_FACT = 14.39964485044579

compute_partial_energy(removed_indices)

Gives total ewald energy for certain sites being removed, i.e. zeroed out.

compute_sub_structure(sub_structure, tol=0.001)

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.

Args:

substructure:

Substructure to compute Ewald sum for.

tol:

Tolerance for site matching in fractional coordinates.

Returns:

Ewald sum of substructure.

eta

forces

The forces on each site as a Nx3 matrix. Each row corresponds to a site.

point_energy

The point energy.

point_energy_matrix

The point space matrix. A diagonal matrix with the point terms for each site in the diagonal elements.

real_space_energy

The real space space energy.

real_space_energy_matrix

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

reciprocal_space_energy

The reciprocal space energy.

reciprocal_space_energy_matrix

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

total_energy

The total energy.

total_energy_matrix

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

compute_average_oxidation_state(site)

Calculates the average oxidation state of a site

Args:

site:

Site to compute average oxidation state

Returns:

Average oxidation state of site.

reaction_calculator Module

This module provides classes that define a chemical reaction.

class BalancedReaction(reactants_coeffs, products_coeffs)

Bases: pymatgen.serializers.json_coders.MSONable

An object representing a complete chemical reaction.

Reactants and products to be specified as dict of {Composition: coeff}.

Args:

reactants:

Reactants as dict of {Composition: amt}.

products:

Products as dict of {Composition: amt}.

all_comp

List of all compositions in the reaction.

calculate_energy(energies)

Calculates the energy of the reaction.

Args:

energies:

dict of {comp:energy}. E.g., {comp1: energy1, comp2: energy2}.

Returns:

reaction energy as a float.

coeffs

Final coefficients of the calculated reaction

elements

List of elements in the reaction

classmethod from_dict(d)

static from_string(rxn_string)

Generates a balanced reaction from a string. The reaciton must already be balanced.

Args:

rxn_string:

The reaction string. For example, “4 Li + O2-> 2Li2O”

Returns:

BalancedReaction

get_coeff(comp)

Returns coefficient for a particular composition

get_el_amount(element)

Returns the amount of the element in the reaction.

Args:

element:

Element in the reaction

Returns:

Amount of that element in the reaction.

normalize_to(comp, factor=1)

Normalizes the reaction to one of the compositions. By default, normalizes such that the composition given has a coefficient of 1. Another factor can be specified.

Args:

comp:

Composition to normalize to

factor:

Factor to normalize to. Defaults to 1.

normalize_to_element(element, factor=1)

Normalizes the reaction to one of the elements. By default, normalizes such that the amount of the element is 1. Another factor can be specified.

Args:

element:

Element to normalize to.

factor:

Factor to normalize to. Defaults to 1.

normalized_repr

A normalized representation of the reaction. All factors are converted to lowest common factors.

normalized_repr_and_factor()

Normalized representation for a reaction For example, 4 Li + 2 O -> 2Li2O becomes 2 Li + O -> Li2O

products

List of products

reactants

List of reactants

to_dict

class ComputedReaction(reactant_entries, product_entries)

Bases: pymatgen.analysis.reaction_calculator.Reaction

Convenience class to generate a reaction from ComputedEntry objects, with some additional attributes, such as a reaction energy based on computed energies.

Args:

reactant_entries:

List of reactant_entries.

products:

List of product_entries.

calculated_reaction_energy

classmethod from_dict(d)

to_dict

class Reaction(reactants, products)

Bases: pymatgen.analysis.reaction_calculator.BalancedReaction

A more flexible class representing a Reaction. The reaction amounts will be automatically balanced.

Reactants and products to be specified as list of pymatgen.core.structure.Composition. e.g., [comp1, comp2]

Args:

reactants:

List of reactants.

products:

List of products.

TOLERANCE = 1e-06

copy()

Returns a copy of the Reaction object.

classmethod from_dict(d)

to_dict

exception ReactionError(msg)

Bases: exceptions.Exception

Exception class for Reactions. Allows more information in exception messages to cover situations not covered by standard exception classes.

smart_float_gcd(list_of_floats)

Determines the great common denominator (gcd). Works on floats as well as integers.

Args:

list_of_floats: List of floats to determine gcd.

structure_analyzer Module

This module provides classes to perform topological analyses of structures.

class RelaxationAnalyzer(initial_structure, final_structure)

Bases: object

This class analyzes the relaxation in a calculation.

Please note that the input and final structures should have the same ordering of sites. This is typically the case for most computational codes.

Args:

initial_structure:

Initial input structure to calculation.

final_structure:

Final output structure from calculation.

get_percentage_bond_dist_changes(max_radius=3.0)

Returns the percentage bond distance changes for each site up to a maximum radius for nearest neighbors.

Args:

max_radius:

Maximum radius to search for nearest neighbors. This radius is applied to the initial structure, not the final structure.

Returns:

Bond distance changes as a dict of dicts. E.g., {index1: {index2: 0.011, ...}}. For economy of representation, the index1 is always less than index2, i.e., since bonding between site1 and siten is the same as bonding between siten and site1, there is no reason to duplicate the information or computation.

get_percentage_lattice_parameter_changes()

Returns the percentage lattice parameter changes.

Returns:

A dict of the percentage change in lattice parameter, e.g., {‘a’: 0.012, ‘b’: 0.021, ‘c’: -0.031} implies a change of 1.2%, 2.1% and -3.1% in the a, b and c lattice parameters respectively.

get_percentage_volume_change()

Returns the percentage volume change.

Returns:

Volume change in percentage, e.g., 0.055 implies a 5.5% increase.

class VoronoiConnectivity(structure)

Bases: object

Computes the solid angles swept out by the shared face of the voronoi polyhedron between two sites

connectivity_array

Returns:

connectivity:

an array of shape [atomi, atomj, imagej]. atomi is the index of the atom in the input structure. Since the second atom can be outside of the unit cell, it must be described by both an atom index and an image index. Array data is the solid angle of polygon between atomi and imagej of atomj

cutoff = 10

get_sitej(site_index, image_index)

Assuming there is some value in the connectivity array at indices (1, 3, 12). sitei can be obtained directly from the input structure (structure[1]). sitej can be obtained by passing 3, 12 to this function

Args:

site_index:

index of the site (3 in the example)

image_index:

index of the image (12 in the example)

max_connectivity

returns the 2d array [sitei, sitej] that represents the maximum connectivity of site i to any periodic image of site j

class VoronoiCoordFinder(structure, target=None)

Bases: object

Uses a Voronoi algorithm to determine the coordination for each site in a structure.

Args:

structure:

Input structure

target:

A list of target species to determine coordination for.

default_cutoff = 10.0

get_coordinated_sites(n, tol=0, target=None)

Returns the sites that are in the coordination radius of site with index n.

Args:

n:

Site number.

tol:

Weight tolerance to determine if a particular pair is considered a neighbor.

Target:

Target element

Returns:

Sites coordinating input site.

get_coordination_number(n)

Returns the coordination number of site with index n.

Args:

n:

site index

get_voronoi_polyhedra(n)

Gives a weighted polyhedra around a site. This uses the voronoi construction with solid angle weights. See ref: A Proposed Rigorous Definition of Coordination Number, M. O’Keeffe, Acta Cryst. (1979). A35, 772-775

Args:

n:

site index

Returns:

A dictionary of sites sharing a common Voronoi facet with the site n and their solid angle weights

contains_peroxide(structure, relative_cutoff=1.2)

Determines if a structure contains peroxide anions.

Args:

structure:

Input structure.

relative_cutoff:

The peroxide bond distance is 1.49 Angstrom. Relative_cutoff * 1.49 stipulates the maximum distance two O atoms must be to each other to be considered a peroxide.

Returns:

Boolean indicating if structure contains a peroxide anion.

solid_angle(center, coords)

Helper method to calculate the solid angle of a set of coords from the center.

Args:

center:

Center to measure solid angle from.

coords:

List of coords to determine solid angle.

Returns:

The solid angle.

structure_matcher Module

This module provides classes to perform fitting of structures.

class AbstractComparator

Bases: pymatgen.serializers.json_coders.MSONable

Abstract Comparator class. A Comparator defines how sites are compared in a structure.

are_equal(sp1, sp2)

Defines how the species of two sites are considered equal. For example, one can consider sites to have the same species only when the species are exactly the same, i.e., Fe2+ matches Fe2+ but not Fe3+. Or one can define that only the element matters, and all oxidation state information are ignored.

Args:

sp1:

First species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

sp2:

Second species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

Returns:

Boolean indicating whether species are considered equal.

static from_dict(d)

get_structure_hash(structure)

Defines a hash for structures. This allows structures to be grouped efficiently for comparison. For example, in exact matching, you should only try to perform matching if structures have the same reduced formula (structures with different formulas can’t possibly match). So the reduced_formula is a good hash. The hash function should be relatively fast to compute relative to the actual matching.

Args:

structure:

A structure

Returns:

A hashable object. Examples can be string formulas, etc.

to_dict

class ElementComparator

Bases: pymatgen.analysis.structure_matcher.AbstractComparator

A Comparator that matches elements. i.e. oxidation states are ignored.

are_equal(sp1, sp2)

True if element:amounts are exactly the same, i.e., oxidation state is not considered.

Args:

sp1:

First species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

sp2:

Second species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

Returns:

Boolean indicating whether species are the same based on element and amounts.

get_structure_hash(structure)

Hash for structure.

Args:

structure:

A structure

Returns:

Reduced formula for the structure is used as a hash for the SpeciesComparator.

class FrameworkComparator

Bases: pymatgen.analysis.structure_matcher.AbstractComparator

A Comparator that matches sites, regardless of species.

are_equal(sp1, sp2)

True if there are atoms on both sites.

Args:

sp1:

First species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

sp2:

Second species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

Returns:

True always

get_structure_hash(structure)

Hash for structure.

Args:

structure:

A structure

Returns:

Number of atoms is a good hash for simple framework matching.

class SpeciesComparator

Bases: pymatgen.analysis.structure_matcher.AbstractComparator

A Comparator that matches species exactly. The default used in StructureMatcher.

are_equal(sp1, sp2)

True if species are exactly the same, i.e., Fe2+ == Fe2+ but not Fe3+.

Args:

sp1:

First species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

sp2:

Second species. A dict of {specie/element: amt} as per the definition in Site and PeriodicSite.

Returns:

Boolean indicating whether species are equal.

get_structure_hash(structure)

Hash for structure.

Args:

structure:

A structure

Returns:

Reduced formula for the structure is used as a hash for the SpeciesComparator.

class StructureMatcher(ltol=0.2, stol=0.3, angle_tol=5, primitive_cell=True, scale=True, attempt_supercell=False, comparator=<pymatgen.analysis.structure_matcher.SpeciesComparator object at 0x103ea1f50>)

Bases: pymatgen.serializers.json_coders.MSONable

Class to match structures by similarity.

Algorithm:

1. Given two structures: s1 and s2

2. Optional: Reduce to primitive cells.

3. If the number of sites do not match, return False

4. Reduce to s1 and s2 to Niggli Cells

5. Optional: Scale s1 and s2 to same volume.

6. Optional: Remove oxidation states associated with sites

7. Find all possible lattice vectors for s2 within shell of ltol.

8. For s1, translate an atom in the smallest set to the origin

9. For s2: find all valid lattices from permutations of the list of lattice vectors (invalid if: det(Lattice Matrix) < half volume of original s2 lattice)

10. For each valid lattice:

    1. If the lattice angles of are within tolerance of s1, basis change s2 into new lattice.

    2. For each atom in the smallest set of s2:

       i. Translate to origin and compare fractional sites in structure within a fractional tolerance. ii. If true:

       ia. Convert both lattices to cartesian and place both structures on an average lattice ib. Compute and return the average and max rms displacement between the two structures normalized by the average free length per atom

       if fit function called:

       if normalized max rms displacement is less than stol. Return True

       if get_rms_dist function called:

       if normalized average rms displacement is less than the stored rms displacement, store and continue. (This function will search all possible lattices for the smallest average rms displacement between the two structures)

Args:

ltol:

Fractional length tolerance. Default is 0.2.

stol:

Site tolerance. Defined as the fraction of the average free length per atom := ( V / Nsites ) ** (1/3) Default is 0.3.

angle_tol:

Angle tolerance in degrees. Default is 5 degrees.

primitive_cell:

If true: input structures will be reduced to primitive cells prior to matching. Default to True.

scale:

Input structures are scaled to equivalent volume if true; For exact matching, set to False.

attempt_supercell:

If set to True and number of sites in cells differ after a primitive cell reduction (divisible by an integer) attempts to generate a supercell transformation of the smaller cell which is equivalent to the larger structure.

comparator:

A comparator object implementing an equals method that declares declaring equivalency of sites. Default is SpeciesComparator, which implies rigid species mapping, i.e., Fe2+ only matches Fe2+ and not Fe3+.

Other comparators are provided, e.g., ElementComparator which matches only the elements and not the species.

The reason why a comparator object is used instead of supplying a comparison function is that it is not possible to pickle a function, which makes it otherwise difficult to use StructureMatcher with Python’s multiprocessing.

find_indexes(s_list, group_list)

Given a list of structures, return list of indices where each structure appears in group_list.

Args:

s_list:

list of structures to check

group_list:

list to find structures in

fit(struct1, struct2)

Fit two structures.

Args:

struct1:

1st structure

struct2:

2nd structure

Returns:

True or False.

fit_anonymous(struct1, struct2)

Performs an anonymous fitting, which allows distinct species in one structure to map to another. E.g., to compare if the Li2O and Na2O structures are similar.

Args:

struct1:

1st structure

struct2:

2nd structure

Returns:

A minimal species mapping that would map struct1 to struct2 in terms of structure similarity, or None if no fit is found. For example, to map the cubic Li2O to cubic Na2O, we need a Li->Na mapping. This method will return [({Element(“Li”): 1}, {Element(“Na”): 1})]. Since O is the same in both structures, there is no O to O mapping required. Note that the return form is a list of pairs of species and occupancy dicts. This complicated return for is necessary because species and occupancy dicts are non-hashable.

static from_dict(d)

get_minimax_rms_anonymous(struct1, struct2)

Performs an anonymous fitting, which allows distinct species in one structure to map to another. E.g., to compare if the Li2O and Na2O structures are similar.

Args:

struct1:

1st structure

struct2:

2nd structure

Returns:

(minimax_rms, min_mapping) min_rms is the minimum of the max rms calculated, and min_mapping is the corresponding minimal species mapping that would map struct1 to struct2. (None, None) is returned if the minimax_rms exceeds the threshold.

get_rms_dist(struct1, struct2)

Calculate RMS displacement between two structures

Args:

struct1:

1st structure

struct2:

2nd structure

Returns:

rms displacement normalized by (Vol / nsites) ** (1/3) and maximum distance between paired sites. If no matching lattice is found None is returned.

group_structures(s_list)

Given a list of structures, use fit to group them by structural equality.

Args:

s_list:

List of structures to be grouped

Returns:

A list of lists of matched structures Assumption: if s1=s2 and s2=s3, then s1=s3 This may not be true for small tolerances.

to_dict

thermochemistry Module

A module to perform experimental thermochemical data analysis.

class ThermoData(data_type, cpdname, phaseinfo, formula, value, ref='', method='', temp_range=(298, 298), uncertainty=None)

Bases: object

A object container for an experimental Thermochemical Data.

Args:

data_type:

The thermochemical data type. Should be one of the following:

fH - Formation enthalpy S - Entropy A, B, C, D, E, F, G, H - variables for use in the various equations for generating formation enthaplies or Cp at various temperatures.

cpdname:

A name for the compound. For example, hematite for Fe2O3.

phaseinfo:

String denoting the phase. For example, “solid”, “liquid”, “gas” or “tetragonal”.

formula:

A proper string formula, e.g., Fe2O3

value:

The value of the data.

ref:

A reference, if any, for the data.

method:

The method by which the data was determined, if available.

temp_range:

Temperature range of validity for the data in Kelvin. Defaults to 298 K only.

uncertainty:

An uncertainty for the data, if available.

classmethod from_dict(d)

to_dict