Magpie_Python module

This module is adapted entirely from Magpie (https://bitbucket.org/wolverton/magpie). If you are using this module, please cite Magpie as:

Ward, A. Agrawal, A. Choudhary, and C. Wolverton, “A general-purpose machine learning framework for predicting properties of inorganic materials,” npj Computational Materials, vol. 2, no. 1, Aug. 2016.

For more information regarding the python version of Magpie, please see https://github.com/ramv2/magpie_python. The chemml.chem.magpie_python module includes (please click on links adjacent to function names for more information):

APEAttributeGenerator: APEAttributeGenerator()

ChargeDependentAttributeGenerator: ChargeDependentAttributeGenerator()

ElementalPropertyAttributeGenerator: ElementalPropertyAttributeGenerator()

ElementFractionAttributeGenerator: ElementFractionAttributeGenerator()

ElementPairPropertyAttributeGenerator: ElementPairPropertyAttributeGenerator()

GCLPAttributeGenerator: GCLPAttributeGenerator()

IonicCompoundProximityAttributeGenerator: IonicCompoundProximityAttributeGenerator()

IonicityAttributeGenerator: IonicityAttributeGenerator()

MeredigAttributeGenerator: MeredigAttributeGenerator()

StoichiometricAttributeGenerator: StoichiometricAttributeGenerator()

ValenceShellAttributeGenerator: ValenceShellAttributeGenerator()

YangOmegaAttributeGenerator: YangOmegaAttributeGenerator()

APRDFAttributeGenerator: APRDFAttributeGenerator()

ChemicalOrderingAttributeGenerator: ChemicalOrderingAttributeGenerator()

CoordinationNumberAttributeGenerator: CoordinationNumberAttributeGenerator()

CoulombMatrixAttributeGenerator: CoulombMatrixAttributeGenerator()

EffectiveCoordinationNumberAttributeGenerator: EffectiveCoordinationNumberAttributeGenerator()

LatticeSimilarityAttributeGenerator: LatticeSimilarityAttributeGenerator()

LocalPropertyDifferenceAttributeGenerator: LocalPropertyDifferenceAttributeGenerator()

LocalPropertyVarianceAttributeGenerator: LocalPropertyVarianceAttributeGenerator()

PackingEfficiencyAttributeGenerator: PackingEfficiencyAttributeGenerator()

PRDFAttributeGenerator: PRDFAttributeGenerator()

StructuralHeterogeneityAttributeGenerator: StructuralHeterogeneityAttributeGenerator()

CompositionEntry: CompositionEntry()

CrystalStructureEntry: CrystalStructureEntry()

class chemml.chem.magpie_python.APEAttributeGenerator

Class to compute features using Atomic Packing Efficiency (APE) of nearby clusters.

Attributes

packing_thresholdfloat: Threshold at which to define a cluster as efficiently packed.
n_nearest_to_evalarray_like: Number of nearest clusters to assess. An array or list of int values. Default : [1, 3, 5]
max_n_typesint: Maximum number of types over which to search for clusters.
radius_propertystr: Name of elemental property to use as atomic radius.

Notes

The APE, as defined by Laws et al. [1], is determined based on the ideal and actual ratio between the central and shell atoms of an atomic cluster with a certain number of atoms. Often, the packing efficiency is described as a ratio between these two quantities:

[Packing efficiency] = [Ideal radius ratio] / [Actual radius ratio]

The ideal ratio is determined based on the ratio between the size of a central atom and the neighboring atoms such that the packing around the central atom is maximized. These optimal ratios for clusters for different numbers of atoms have been tabulated by Miracle et al. [2].

The actual ratio is computed by dividing the radius of the central atom by the average of the central atoms.

We currently use this framework to create two types of features:

Distance to nearest clusters with a packing efficiency better than a certain threshold. If there are fewer than a requested number of efficiently packed clusters in an alloy system, the average is taken to be the average distance to all of the clusters. These features are designed to measure the availability of efficiently-packed atomic configurations in the liquid.

Mean packing efficiency of the system assuming that the composition of the first nearest neighbor shell is equal to the composition of the system. Each atom type is surrounded by the number of atoms that maximizes the packing efficiency. As shown in recent work by Laws et al. [1], bulk metallic glasses are known to form when the clusters around all types of atom have the same composition as the alloy and are efficiently packed. We compute the average APE for each atom in the system, under this assumption, and the average deviation from perfect packing.

Advanced Notes

This algorithm currently evaluates all possible clusters provided a list of elements. As the number of clusters scales with N!, the runtime of this algorithm scales with N!.

For now, we only search for clusters with up to 7 atoms (max_n_types) in order to avoid this combinatorial problem. In practice, the algorithm picks the top 7 alloys with the highest fractions. While not idea, this might work in practice since most alloys have fewer than 7 main components. Many alloys >10 elements in the specification, but many are impurities that may not be present in large enough amounts to really affect the determination of efficiently packed clusters.

References

model for bulk metallic glasses,” Nature Communications, vol. 6, p. 8123, Sep. 2015. .. [2] D. B. Miracle, E. A. Lord, and S. Ranganathan, “Candidate Atomic Cluster Configurations in Metallic Glass Structures,” MATERIALS TRANSACTIONS, vol. 47, no. 7, pp. 1737 – 1742, 2006. .. [3] D. B. Miracle, D. V. Louzguine-Luzgin, L. V. Louzguina-Luzgina, and A. Inoue, “An assessment of binary metallic glasses: correlations between structure, glass forming ability and stability,” International Materials Reviews, vol. 55, no. 4, pp. 218–256, Jul. 2010.

classmethod compute_APE(n_neighbors=None, center_radius=None, neigh_eff_radius=None, radii=None, center_type=None, shell_types=None)

Function to compute the APE of a cluster, given the identities of the central and 1st neighbor atoms or just the number of neighbors and the radii.

Here, we follow the formulation given by Laws et al. [1].

APE = ideal radius ratio / (radius of central atom / effective radius of nearest neighbors)

Parameters

n_neighborsint: Number of 1st nearest neighbors in the cluster.
center_radiusfloat: Radius of the central atom.
neigh_eff_radiusfloat: Effective radius of the 1st shell. Usually computed as the average radius of all atoms in the shell.
radiiarray-like: Radius of each atom type. A list of float values.
center_typeint: Type of atom in the center.
shell_typesarray-like: Number of atoms of each type in the outer shell. Must be same length as radii.

Returns

outputfloat: APE, as defined in the function description.

classmethod compute_cluster_compositions(e_ids, clusters)

Function to compute the compositions of a list of atomic clusters.

The composition includes both atoms in the first nearest neighbor shell and the atom in the center of the cluster.

Parameters

e_ids: array-like: Ids of the elements from which clusters are composed. A list of int values.
clustersarray-like: Clusters to convert. List of identity shell compositions for each type of central atom. Ex: clusters[1][2] is an array defining the number of atoms of each type for clusters with an atom of type 1 in the center. A list containing a list of int values.

Returns

outputarray-like: Compositions found in this cluster. A list of CompositionEntry’s.

classmethod determine_optimal_APE(central_atom_type, shell_composition, radii)

Function to compute the optimal APE for a cluster with a certain atom type in the center and composition in the cell.

Parameters

central_atom_typeint: Element id (Z - 1) of th central atom.
shell_compositionCompositionEntry: Composition of the nearest-neighbor shell.
radiiarray-like: Lookup table of elemental radii. A list of float values.

Returns

outputfloat: The optimal APE.

Notes

This algorithm finds the number of atoms in the shell such that the APE of the cluster is closest to 1. Note: This calculation assumes that sites in the first nearest-neighbor shell can be partially-occupied.

classmethod find_efficiently_packed_clusters(radii, packing_threshold)

Function to find all clusters with better APE than a certain threshold, given a list of atomic radii.

The packing efficiency is defined as abs(1 - APE).

Parameters

radiiarray-like: Radii of elements. A list of float values.
packing_thresholdfloat: Desired packing limit threshold. A “default” choice would be 0.05.

Returns

outputarray-like: A list of efficiently packed structures for each atom type as the central atom. Ex: x[0][1] is the 2nd efficiently packed cluster with atom type 0 as the central atom. A list containing a list of int values.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

get_closest_compositions(target_composition, other_compositions, n_closest, p_norm)

Function to get closest compositions from a given target composition.

Parameters

target_compositionCompositionEntry: Composition from which to measure distance.
other_compositionsarray-like: Compositions whose distance from the target will be ranked. A list of CompositionEntry’s.
n_closestint: Number of closest compounds to return.
p_normint: P-norm to use when computing distance.

Returns

distarray-like: Distances of the compositions from the target composition. A list of float values.
compsarray-like: A list of CompositionEntry’s.

classmethod get_cluster_range(radii, packing_threshold)

Function compute the maximum and minimum possible cluster sizes, given a list of radii.

The smallest possible cluster has the smallest atom in the center and the largest in the outside. The largest possible has the largest in the inside and the smallest in the outside.

Parameters

radiiarray-like: Radii of elements in the system. A list of float values.
packing_thresholdfloat: APE defining maximum packing threshold.

Returns

min_cluster_sizeint: Minimum cluster size as defined by number of atoms in the shell.
max_cluster_sizeint: Maximum cluster size as defined by number of atoms in the shell.

set_n_nearest_to_eval(values)

Function to define the number of nearest neighbor clusters to evaluate when computing features.

Parameters

valuesarray-like: Number of nearest clusters to assess. An array or list of int values.

set_packing_threshold(threshold)

Function to define the threshold at which a cluster is considered efficiently packed.

Parameters

thresholdfloat: Desired threshold. Default: 0.01

Raises

ValueError: If threshold value is negative.

set_radius_property(prop)

Function to set the name of the elemental property used to define radii.

By default uses the “MiracleRadius” property which is from an assessment by Miracle et al. [2].

Parameters

propstr: Name of property used to define radii.

class chemml.chem.magpie_python.APRDFAttributeGenerator

Class to generate attributes based on the Atomic Property Weighted Radial Distribution Function (AP-RDF) approach of Fernandez et al. [1].

User can specify the cutoff distance for the AP-RDF, the number of points to evaluate it, the smoothing factors for the RDF peaks, and the properties used for weighting. The recommended values of these parameters have yet to be determined, please contact Logan Ward or the authors of this paper if you have questions or ideas for these parameters.

Attributes

cut_off_distancefloat: Cutoff distance for RDF.
num_pointsint: Number of points to evaluate.
smooth_parameterfloat: Smoothing parameter for AP-RDF.
elemental_propertieslist: Elemental properties to be associated with this class for the generation of features.

References

Weighted Radial Distribution Functions Descriptors of Metal–Organic Frameworks for the Prediction of Gas Uptake Capacity,” The Journal of Physical Chemistry C, vol. 117, no. 27, pp. 14095–14105, Jul. 2013.

add_elemental_properties(properties)

Function to provide a list of elemental properties to be used to compute features.

Parameters

propertiesarray-like: Properties to be included. A list of strings containing property names.

add_elemental_property(property_name)

Function to add an elemental property to self.elemental_properties in order to be used to compute features.

Parameters

propertystr: Property to be added.

clear_elemental_properties(): Function to clear the list of elemental properties.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

set_cut_off_distance(d)

Function to set cut off distance used when computing PRDF.

Parameters

dfloat: Cut off distance.

set_num_points(num_points)

Function to set the number of points at which to evaluate AP-RDF.

Parameters

num_pointsint: Desired number of windows.

set_smoothing_parameter(b)

Function to set smoothing factor used when computing PRDF.

Parameters

bfloat: Smoothing factor.

class chemml.chem.magpie_python.ChargeDependentAttributeGenerator

Class to generate attributes derived from the oxidation states of elements in a material. Based on work by Deml et al.[1].

Notes

These features are based on the formal charges of materials determined using the OxidationStateGuesser. Currently implemented features: Statistics of formal charges (min, max, range, mean, variance) Cumulative ionization energies/ electron affinities Difference in electronegativities between cation and anion. For materials that the algorithm fails to find charge states, NaN is set for all features.

References

“Predicting density functional theory total energies and enthalpies of formation of metal-nonmetal compounds by linear regression,” Physical Review B, vol. 93, no. 8, Feb. 2016.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.ChemicalOrderingAttributeGenerator

Class to compute attributes based on chemical ordering of structure. Determines average Warren-Cowley ordering parameter for the bond network defined by the Voronoi tessellation of a structure.

Attributes

shellslist: Index of shells to compute features for.
weightedbool: Whether to compute features using weighting or not.

Notes

For each atom in the structure, the average Warren-Cowley ordering parameter is determined by computing the average magnitude of ordering parameter for each type for all atoms in a structure. The ordering parameter is 0 for a perfectly-random distribution, so this average represents an average degree of “ordering” in the structure. This attribute is computed for several nearest-neighbor shells (1st, 2nd, and 3rd by default).

There are two options for computing order parameters: Weighted and unweighted. The former is computed by weighing the contribution of each neighboring atom by the fraction of surface area corresponding to boundaries between that atom and the central atom. The former considers all neighbors weighted equally, which means they are very sensitive to the introduction of small faces due to numerical problems inherent to the Voronoi tessellation. Full details is available in the Vassal documentation for VoronoiCellBasedAnalysis.getNeighborOrderingParameters().

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

set_shells(shells)

Function to set which nearest-neighbor shells to consider when generating features.

Parameters

shells: list: Desired shell indices.

set_weighted(weighted)

Function to set whether to consider face sizes when computing ordering parameters.

Parameters

weighted: bool: Whether to weigh using face sizes.

class chemml.chem.magpie_python.CompositionEntry(composition=None, element_ids=None, element_names=None, fractions=None)

Class that defines a CompositionEntry object. Mainly used to store ids, names and fractions of elements belonging to a single compound.

Attributes

lp_element_namesarray-like: Names of each element. A list of string values.
lp_sorting_orderarray-like: Rank of each element (used in display order). A list of int values.
element_idsarray-like: Element ids present in composition. A list of int values.
element_namesarray-like: Element names present in composition. A list of string values.
fractionsarray-like: Fraction of each element. A list of float values.
number_in_cellfloat: Number of atoms in cell (used to convert when printing).

combine_compositions(total_comp, add_comp, multiplier)

Function to add one CompositionEntry to another.

Parameters

total_compdict: Dictionary containing element ids and fractions as keys and values respectively. Composition to be added to.
add_compdict: Dictionary containing element ids and fractions as keys and values respectively. Composition to add.
multiplierfloat: Factor to multiply with.

Returns

get_element_fraction(name=None, id=None)

Function to get the element fraction given either the name or the id of the element.

Parameters

namestr: Name of the element.
idint: Id of the element.

Returns

fractionfloat: Elemental fraction.

get_element_fractions()

Function to get the element fractions in the composition.

Returns

element_fractionsarray-like: List of element fractions (float).

get_element_ids()

Function to get the element ids in the composition.

Returns

element_idsarray-like: List of element ids (int).

get_element_names()

Function to get the element names in the composition.

Returns

element_namesarray-like: List of element names (strings).

classmethod import_composition_list(file_path)

Function to read a list of compositions from a file.

Parameters

file_pathstr: Path to the file containing the list of compositions.

Returns

composition_listarray-like: A list of CompositionEntry’s corresponding to the file contents.

classmethod import_values_list(file_path)

Function to read a list of target property values from a file.

Target property values are used to develop machine learning models.

Parameters

file_pathstr: Path to the file containing the list of compositions.

Returns

property_listarray-like: A list of target property values (floats) corresponding to the file contents.

parse_composition(composition)

Function to parse a string containing the composition. Supports parentheses and addition compounds (ex: Na_2CO_3-10H_2O). Note, will not properly parse addition compounds inside parentheses (ex: Na_2(CO_3 - 10H_2O)_1).

Parameters

compositionstr: The chemical formula of a material.

Returns

outputdict: Dictionary containing element ids and fractions as keys and values respectively.

Raises

ValueError: If closing parenthesis is missing. If parenthesis is not recognized.

parse_element_amounts(composition)

Function to compute fractions of element given a string of elements and amounts.

Parameters

compositionstr: Composition of a material.

Returns

tmp_entrydict: Dictionary containing element ids and fractions as keys and values respectively.

Raises

ValueError: If either element names or ids are not recognized. If element amount is not a number.

classmethod print_number(fraction, n_in_formula_unit)

Function to print out the number of atoms in a formula unit for each element given its fraction.

Parameters

fractionarray-like: List of element fractions (floats) to be printed.
n_in_formula_unitint: Number of atoms in a formula unit.

Returns

outputstr: Formatted fractions.

set_composition(amounts, element_ids=None, element_names=None, to_sort=True)

Function to set the composition of this entry. Checks to make sure all elements have positive amounts.

Parameters

amountsarray-like: List of amounts (float) for each element.
element_idsarray-like: List of element ids (integers).
element_namesarray-like: List of element names (strings).

Raises

ValueError: If either element names or ids are missing. If lists have different lengths.

sort_and_normalize(to_sort=True)

Function to sort the element ids based on their electronegativity order and normalizes the fractions. Makes sure the entry is in a proper format. Must be run from constructor.

Parameters

to_sortbool: Whether to sort as well as normalize or just normalize this instance.

class chemml.chem.magpie_python.CoordinationNumberAttributeGenerator

Class to compute attributes based on the coordination number. Uses the Voronoi tessellation to define the coordination network.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

class chemml.chem.magpie_python.CoulombMatrixAttributeGenerator

Class to compute attributes using the Coulomb Sine Matrix representation. Based on work by Faber et al. [1].

Attributes

n_eigenvaluesint: Maximum number of atoms to consider. Defines number of attributes.

Notes

This method works by computing an approximation for the Coulomb matrix that considers periodicity. Specifically, we use the Coulomb Sine matrix, which is described in detail in the Faber et al.[1]. For molecules, the Coulomb matrix is defined as

\[C_{i,j} &= Z_i^{2.4} & ext{if} i=j\ &= Z_i Z_j / r_ij & ext{if} i != j\]

The eigenvalues of this matrix are then used as attributes. In order to provided a fixed number of attributes, the first N attributes are defined to be the N eigenvalues from the Coulomb matrix. The remaining attributes are defined to be zero.

The Coulomb Matrix attributes are dependant on unit cell choice. Please consider transforming your input crystal structures to the primitive cell before using these attributes.

References

“Crystal structure representations for machine learning models of formation energies,” International Journal of Quantum Chemistry, vol. 115, no. 16, pp. 1094–1101, Apr. 2015.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

set_n_eigenvalues(x)

Function to set the number of eigenvalues used in representation.

Parameters

xint: Desired number.

class chemml.chem.magpie_python.CrystalStructureEntry(structure, name, radii)

Class to represent a crystal structure.

Attributes

structureCell: Crystal structure represented in the form of a Cell.
namestr: Name given to denote this structure. Mainly used for book-keeping.
radiiarray-like: List of radii (floats) for various atoms in the periodic table.
voronoiVoronoiCellBasedAnalysis: Tool used to query properties of the tessellation.

clear_representations(): Function to clear out the representations used when computing attributes.

compute_composition()

Function to compute the composition of this crystal.

Raises

Exception: If element name is not recognized.

compute_voronoi_tessellation()

Function to compute the voronoi tessellation of this structure.

Returns

voronoiVoronoiCellBasedAnalysis: Tool used to query properties of the tessellation.

get_name()

Function to get the name of this entry.

Returns

namestr: Name given to denote this structure. Mainly used for book-keeping.

get_structure()

Function to get link to the structure.

Returns

structureCell: Structure this entry represents.

classmethod import_structures_list(dir_path)

Function to read a list of crystal structures from a directory.

Parameters

dir_pathstr: Path to the directory containing the list of vasp files.

Returns

structures_listarray-like: A list of CrystalStructureEntry’s corresponding to the file contents.

replace_elements(replacements)

Function to create a new entry by replacing elements on this entry.

Parameters

replacementsdict: Dictionary of elements to replace. Key: Old element, Value: New element.

Returns

new_entryCrystalStructureEntry: New entry formed by replacing the current elements with the replacement map.

class chemml.chem.magpie_python.EffectiveCoordinationNumberAttributeGenerator

Compute attributes based on the effective coordination number.

The effective coordination number can be thought of as a face-size-weighted coordination number. It is computed by the formula

\[N_{eff} = \displaystyle\]

rac{1}{sum[( rac{f_i}{SA})^2]}

where :math: f_i is the area of face :math: i and :math: SA is the surface area of the entire cell.

The effective coordination number has major benefit: stability against the additional of a very small face. Small perturbations in atomic positions can break symmetry in a crystal, and lead to the introduction of small faces. The conventional coordination number treats all faces equally, so the coordination number changes even when one of these small faces is added.

One approach in the literature is to first apply a screen on small faces (e.g., remove any smaller than 1% of the total face area), which still runs into problems with discontinuity for larger displacements.

Our approach is differentiable with respect to the additional of a small face (ask Logan if you want the math), and also captures another interesting effect small coordination numbers for Voronoi cells with a dispersity in face sizes. For example, BCC has 14 faces on its voronoi cell. 8 large faces, and 6 small ones. Our effective face size identifies a face size of closer to 8, the commonly-accepted value of the BCC coordination number, than 14 reported by the conventional measure. Additional, for systems with equal-sized faces (e.g., FCC), this measure agrees exactly with conventional reports.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

mean_abs_dev(data)

Function to compute the mean absolute deviation of an array-like collection of numbers.

Parameters

dataarray-like: A NumPy array of float values.

Returns

outputfloat: The mean absolute deviation.

class chemml.chem.magpie_python.ElementFractionAttributeGenerator

Class to set the element fractions as the features of materials.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.ElementPairPropertyAttributeGenerator

Class to generate attributes based on the properties of constituent binary systems. Computes the minimum, maximum and range of all pairs in the material, and the fraction-weighted mean and variance of all pairs. Variance is defined as the mean absolute deviation from the mean over all pairs. If an entry has only one element, the value of NaN is used for all attributes.

Attributes

elemental_pair_propertieslist: Elemental properties to be associated with this class for the generation of features.
pair_lookup-datadict: Dictionary containing the property name as the key and a list of floats as the value.

add_elemental_pair_properties(properties)

Function to provide a list of elemental pair properties to be used to compute features.

Parameters

propertiesarray-like: Properties to be included. A list of strings containing property names.

add_elemental_pair_property(property)

Function to add an elemental pair property to be used to compute features.

Parameters

propertystr: Property to be added.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If no elemental properties are set. If input is not of type list. If items in the list are not CompositionEntry instances.

load_pair_lookup_data(): Function to load the property values into self.lookup_data for the computation of features.

remove_elemental_pair_properties(properties)

Function to remove a list of elemental pair properties from the list of elemental properties.

Parameters

propertiesarray-like: Properties to be removed. A list of strings containing property names.

remove_elemental_pair_property(property)

Function to remove an elemental pair property from the list of elemental properties.

Parameters

propertystr: Property to be removed.

class chemml.chem.magpie_python.ElementalPropertyAttributeGenerator(use_default_properties=True)

Class to set up and generate descriptors based on elemental property statistics. Computes the mean, maximum, minimum, range, mode and mean absolute deviation of all elemental properties provided.

Attributes

elemental_propertiesarray-like: Elemental properties to be associated with this class for the generation of features.
lookup-datadict: Dictionary containing the property name as the key and a list of floats as the value.

add_elemental_properties(properties)

Function to provide a list of elemental properties to be used to compute features.

Parameters

propertiesarray-like: Properties to be included. A list of strings containing property names.

add_elemental_property(property)

Function to add an elemental property to self.elemental_properties in order to be used to compute features.

Parameters

propertystr: Property to be added.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If no elemental properties are set. If input is not of type list. If items in the list are not CompositionEntry instances.

load_lookup_data(): Function to load the property values into self.lookup_data for the computation of features.

remove_elemental_properties(properties)

Function to remove a list of elemental properties from the list of elemental properties.

Parameters

propertiesarray-like: Properties to be removed. A list of strings containing property names.

remove_elemental_property(property)

Function to remove an elemental property from self.elemental_properties.

Parameters

propertystr: Property to be removed.

class chemml.chem.magpie_python.GCLPAttributeGenerator

Class to compute features based on the T=0K ground state.

Attributes

GCLPCalculatorGCLPCalculator: A GCLPCalculator instance.
count_phasesbool: Flag to include or exclude the number of phases at equilibrium.

Notes

Features: 1. Formation energy. 2. Number of phases in equilibrium. 3. Distance from closest composition (i.e., ||x_i - x_{i,f}||_2 for each component i for phase f). 4. Average distance from all neighbors. 5. Quasi-entropy (sum x_i * ln(x_i) where x_i is fraction of phase). Certain values of the number of phases in equilibrium and “quasi-entropy” are only accessible to systems with larger number of elements. Useful if you do not want to consider the number of components in an alloy as a predictive variable.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

set_count_phases(count_phases)

Function to set variable to count number of phases at equilibrium. In some cases, you may want to exclude this as a feature because it is tied to the number of components in the compound.

Parameters

count_phasesbool: Desired setting.

set_phases(phases, energies)

Function to define phases used when computing ground states.

Parameters

phasesarray-like: Compositions to consider. A list of CompositionEntry’s.
energiesarray-like: Corresponding energies. A list of float values.

class chemml.chem.magpie_python.IonicCompoundProximityAttributeGenerator

Class to generate attributes based on the distance of a composition from a compositions that can form charge-neutral ionic compounds.

Attributes

max_formula_unitint: Maximum number of atoms per formula unit.

Notes

This generator only computes a single feature: the L_1 distance between the composition of an entry and the nearest ionic compound (determined using IonicCompoundFinder). For a compound where it is not possible to form an ionic compound (e.g., only metallic elements), the entry is assigned arbitrarily large distance (equal to the number of elements in the alloy). The one adjustable parameter in this calculation is the maximum number of atoms per formula unit used when looking for ionic compounds. For binary compounds, the maximum conceivable number of elements in a formula unit is for a compound with a 9+ and a 5- species, which has 14 atoms in the formula unit. Consequently, we recommend using 14 or larger for this parameter.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

set_max_formula_unit(size)

Function to define the maximum number of atoms per formula unit.

Parameters

sizeint: Desired size.

class chemml.chem.magpie_python.IonicityAttributeGenerator

Class to generate the attributes based on the ionicity of a compound. Creates attributes based on whether it is possible to form a charge-neutral ionic compound, and two features based on a simple measure of “bond ionicity” (see Ref. [1]).

Notes

Bond ionicity is defined as: .. math:: I(x,y) = 1 - exp(-0.25* [chi(x) - chi(y)]^2) Maximum ionic character: Max I(x,y) between any two constituents. Mean ionic character: :math: sum x_i * x_j * I(i,j) where :math: x_i is the fraction of element :math: i and :math: chi(x) is the electronegativity of element :math: x.

References

introduction, Hoboken: John Wiley, 2014.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.LatticeSimilarityAttributeGenerator

Compute similarity of structure to several simple lattices.

Notes

Determined by comparing the shape of each coordination polyhedron in the structure (as determined using a Voronoi tessellation) to those in a reference lattice.

Similarity is computed by summing the difference in the number of faces with each number of edges between a certain Voronoi cell and that of the reference lattice. This difference is then normalized by the number of faces in the reference lattice, and averaged over all atoms to produce a “similarity index”. In this form, structures based on the reference lattice have a match of 0, which becomes larger with increase dissimilarity.

For now we consider the BCC, FCC (which has the same coordination polyhedron shape as HCP), and SC lattices.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

class chemml.chem.magpie_python.LocalPropertyDifferenceAttributeGenerator(shells=None)

Class to compute attributes based on the difference in elemental

properties between neighboring atoms.

elemental_propertieslist: Elemental properties to be associated with this class for the generation of features.
shellsarray-like: Shells to consider. A list of int values.
attr_namestr: Property Name.

For an atom, its “local property difference” is computed by:

\[\displaystyle\]

rac{sum_n f_n * left|p_{atom} - p_n ight|}{

sum_n f_n}

where :math: f_n is the area of the face associated with neighbor :math: n, p_{atom} is the elemental property of the central atom, and :math: p_n is the elemental property of the neighbor atom.

For shells past the 1st nearest neighbor shell, the neighbors are identified by finding all of the unique faces on the outside of the polyhedron formed by the previous neighbor shell. This list of faces will faces corresponding to all of the atoms in the desired shell and the total weight for each atom is defined by the total area of the faces corresponding to that atom (there may be more than one).

By default, this class considers the only the 1st nearest neighbor shell.

This parameter is computed for all elemental properties stored in Composition Entry ElementalProperties.

add_elemental_properties(properties)

Function to provide a list of elemental properties to be used to compute features.

Parameters

propertiesarray-like: Properties to be included. A list of strings containing property names.

add_elemental_property(prop)

Function to add an elemental property to self.elemental_properties in order to be used to compute features.

Parameters

propertystr: Property to be added.

add_shell(shell)

Function to add shell to the list used when computing attributes.

Parameters

shellsint: Index of nearest-neighbor shell.

Raises

ValueError: If shell is negative.

add_shells(shells)

Function to add a list of shells to be used when computing attributes.

Parameters

shellsarray-like: Shells to be considered. A list of int values.

clear_elemental_properties(): Function to clear all the elemental properties.

clear_shells(): Function to clear the list of shells.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

get_atom_properties(voro, shell, prop_values)

Function to compute the properties of a certain neighbor cell for each atom, given the Voronoi tessellation and properties of each atom type.

Parameters

voroVoronoiCellBasedAnalysis: Analysis tool.
shellint: Index of shell.
prop_valuesarray-like: Properties of each atom type. A list or NumPy array of float values.

Returns

outputarray-like: Properties of each atom. A list or NumPy array of float values.

remove_elemental_properties(properties)

Function to remove a list of elemental properties from the list of elemental properties.

Parameters

propertiesarray-like: Properties to be removed. A list of strings containing property names.

remove_elemental_property(property)

Function to remove an elemental property from self.elemental_properties.

Parameters

propertystr: Property to be removed.

class chemml.chem.magpie_python.LocalPropertyVarianceAttributeGenerator(shells=None)

Class to compute attributes based on the local variance in elemental properties around each atom.

Notes

This class is meant to be used in conjunction with ElementFractionAttributeGenerator and ValenceShellAttributeGenerator. To match the attributes from the Meredig et al. [1] paper, use all three attribute generators.

References

unconstrained composition space with machine learning,” Physical Review B, vol. 89, no. 9, Mar. 2014.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.PRDFAttributeGenerator

Class to compute attributes based on the Pair Radial Distribution Function (PRDF). Based on work by Schutt et al. [1].

Attributes

cut_off_distancefloat: Cutoff distance for PRDF.
n_pointsint: Number of distance points to evaluate.
element_listarray-like: Elements to use in PRDF. A list of int values.

References

and E. K. U. Gross, “How to represent crystal structures for machine learning: Towards fast prediction of electronic properties,” Physical Review B, vol. 89, no. 20, May 2014.

add_element(id=None, name=None)

Function to add element to list used when computing PRDF.

Parameters

idint: ID of element (Atomic number - 1).
namestr: Name of the element.

Raises

ValueError: If both arguments are None. If entered element name can not be found in database.

clear_element_list(): Function to clear out the elements in element list.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

set_cut_off_distance(d)

Function to set the maximum distance to consider when computing the PRDF.

Parameters

dfloat: Desired cutoff distance.

set_elements(entries)

Function to set the elements when computing PRDF.

Parameters

dataarray-like: A list of CompositionEntry’s containing each element to be added.

set_n_points(n_p)

Function to set the number of points on each PRDF to store.

Parameters

n_pint: Number of evaluation points.

class chemml.chem.magpie_python.PackingEfficiencyAttributeGenerator

Class to compute attributes based on packing efficiency. Packing efficiency is determined by finding the largest sphere that would fit inside each Voronoi cell and comparing the volume of that sphere to the volume of the cell.

Notes

For now, the only attribute computed by this generator is the maximum packing efficiency for the entire cell. This is computed by summing the total volume of all spheres in all cells, and dividing by the volume of the unit cell.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

class chemml.chem.magpie_python.StoichiometricAttributeGenerator(use_default_norms=True)

Class to set up and generate descriptors based on the stoichiometry of a given material. Includes features that are only based on fractions of elements, but not what those elements actually are.

Attributes

p_normslist: Exponents to be used in computing various norms.

add_p_norm(norm)

Function to add a p norm to be computed.

Parameters

normint: Desired norm.

Raises

ValueError: If norm is 1.

add_p_norms(norms)

Function to add a list of p norms to be computed.

Parameters

normarray-like: Desired norms. A list of int values.

clear_p_norms(): Function to clear out the list of p norms to be computed.

generate_features(entries)

Function to generate the stoichiometric features.

Computes the norms based on elemental fractions.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.StructuralHeterogeneityAttributeGenerator

Class to compute attributes based on heterogeneity in structure. Measures variance in bond lengths (both for a single atom and between different atoms) and atomic volumes. Also considers the number of unique coordination polyhedron shapes. Bond lengths, atomic volumes, and coordination polyhedra are based on the Voronoi tessellation of the structure.

Notes

Current attributes: 1. Mean absolute deviation in average bond length for each atom, normalized by mean for all atoms. 2. Minimum in average bond length, normalized by mean for all atoms. 3. Maximum in average bond length, normalized by mean for all atoms. 4. Mean bond length variance between bonds across all atom. 5. Mean absolute deviation in bond length variance. 6. Minimum bond length variance. 7. Maximum bond length variance. 8. Mean absolute deviation in atomic volume, normalized by mean atomic volume.

Here, bond length variation for a single atom is defined as: .. math:: hat{l} = <l_i - ar{l}> where :math: l_i is the distance between an atom and one of its neighbors.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Crystal structures for which features are to be generated. A list of CrystalStructureEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CrystalStructureEntry instances.

class chemml.chem.magpie_python.ValenceShellAttributeGenerator

Class that generates attributes based on fraction of electrons in valence shell of constituent elements. Creates 4 features: [Composition-weighted mean # of electrons in the {s,p, d,f} shells]/[Mean # of Valence Electrons] Originally presented by: Meredig et al. [1].

References

unconstrained composition space with machine learning,” Physical Review B, vol. 89, no. 9, Mar. 2014.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

class chemml.chem.magpie_python.YangOmegaAttributeGenerator

Class to compute the attributes \(\Omega\) and \(\delta\)

developed by Yang and Zhang [1]. These parameters are based on the liquid formation enthalpy and atomic sizes of elements respectively and were originally developed to predict whether a metal alloy will form a solid solution of bulk metallic glass.

math:: Omega is derived from the melting temperature, ideal mixing

entropy, and regular solution solution interaction parameter ( :math: Omega_{i,j}) predicted by the Miedema model for binary liquids. Specifically, it is computed using the relationship: .. math:: Omega = displaystyle

rac{T_m Delta S_{mix}} {|\Delta H_{mix}|}

where :math: T_m is the composition-weighted average of the melting temperature, :math: Delta S_{mix} is the ideal solution entropy, and :math: Delta H_{mix} is the mixing enthalpy. The mixing enthalpy is computed using the Miedema mixing enthalpies tabulated by Takeuchi and Inoue [2] where: .. math:: Delta H_{mix} = displaystylesum Omega_{i,j} c_i c_j and :math: Omega_{i,j} = 4 * Delta H_{mix}. :math: delta is related to the polydispersity of atomic sizes, and is computed using the relationship: .. math:: delta = [displaystylesum c_i (1 -

rac{r_i}{r_{

average})^2]^0.5 where :math: r_i is the atomic size. Here, we use the atomic radii compiled by Miracle et al. [3] rather than those compiled by Kittel, as in the original work.

solid-solution in multi-component alloys,” Materials Chemistry and Physics, vol. 132, no. 2–3, pp. 233–238, Feb. 2012. .. [2] A. Takeuchi and A. Inoue, “Classification of Bulk Metallic Glasses by Atomic Size Difference, Heat of Mixing and Period of Constituent Elements and Its Application to Characterization of the Main Alloying Element,” MATERIALS TRANSACTIONS, vol. 46, no. 12, pp. 2817–2829, 2005. .. [3] D. B. Miracle, D. V. Louzguine-Luzgin, L. V. Louzguina-Luzgina, and A. Inoue, “An assessment of binary metallic glasses: correlations between structure, glass forming ability and stability,” International Materials Reviews, vol. 55, no. 4, pp. 218–256, Jul. 2010.

generate_features(entries)

Function to generate features as mentioned in the class description.

Parameters

entriesarray-like: Compositions for which features are to be generated. A list of CompositionEntry’s.

Returns

featuresDataFrame: Features for the given entries. Pandas data frame containing the names and values of the descriptors.

Raises

ValueError: If input is not of type list. If items in the list are not CompositionEntry instances.

Magpie_Python module

Attributes

Notes

Advanced Notes

References

Parameters

Returns

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Raises

Parameters

Attributes

References

Parameters

Parameters

Parameters

Returns

Raises

Parameters

Parameters

Parameters

Notes

References

Parameters

Returns

Raises

Attributes

See Also

Notes

Parameters

Returns

Raises

Parameters

Parameters

Attributes

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Raises

Parameters

Returns

Parameters

Raises

Parameters

Parameters

Returns

Raises

Attributes

Notes

References

Parameters

Returns

Raises