magpie.attributes.generators.composition

Class APEAttributeGenerator

java.lang.Object

magpie.attributes.generators.BaseAttributeGenerator

magpie.attributes.generators.composition.APEAttributeGenerator

All Implemented Interfaces:

java.io.Serializable, Commandable, Options

public class APEAttributeGenerator
extends BaseAttributeGenerator

Compute attributes using Atomic Packing Efficiency (APE) of nearby clusters. The atomic packing efficiency, as defined by Laws et al. is determined based on the ideal and actual ratio between the central and shell atoms of an atomic cluster with a certain number 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 packing around the central atom is maximized. These optimal ratios for clusters of different numbers of atoms have been tabulated by Miracle et al..

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

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

1. Distance to nearest clusters with a packing efficiency better than a certain threshold. If there are fewer than a request number of efficiently packed clusters in an alloy system, the average is taken to be the average distance to all of the clusters. These attributes are designed to measure the availability of efficiently-packed atomic configurations in the liquid.
2. Mean packing efficiency of 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., 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. On a 3.5GHz processor, this can find all clusters with up to 8 types in ~20 seconds. However, as the number of clusters scales with N!, the runtime for this algorithm scales with N!.

For now, we only search for clusters with up to 7 atoms (see MaxNTypes) in order to avoid this combinatorial problem. In practice, the algorithm picks the top 7 alloys with the highest fractions. While not ideal, this might work in practice since most alloys have fewer than 7 main components. Many alloys have >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.

Usage: <packing threshold> -neighbors <neighbors to evaluate>
packing threshold: Threshold at which to define a cluster as "efficiently-packed" (suggestion = 0.01)
neighbors to evaluate: List of number of nearest neighbors to consider when generating attributes (suggestion = 1 3 5)

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	MaxNTypes Maximum number of types over which to search for clusters.

Constructor Summary

Constructors

Constructor and Description
APEAttributeGenerator() Create generator with default settings.

Method Summary

Modifier and Type	Method and Description
void	addAttributes(Dataset data) Generate new attributes for a dataset.
static double	computeAPE(double[] radii, int centerType, int[] shellTypes) Compute the APE of a cluster, provided the identities of the central and 1st neighbor atoms.
static double	computeAPE(int NNeighbors, double centerRadius, double neighEffRadius) Compute the APE provided the number of neighbors and radii.
static java.util.List<CompositionEntry>	computeClusterCompositions(int[] elements, java.util.List<java.util.List<int[]>> clusters) Compute the compositions of a list of atomic clusters.
static double	determineOptimalAPE(int centralAtomType, CompositionEntry shellComposition, double[] radii) Compute the optimal APE for a cluster with a certain atom type in the center and composition in the cell.
static java.util.List<java.util.List<int[]>>	findEfficientlyPackedClusters(double[] radii, double packingThreshold) Provided a list of atomic radii, find all clusters with better than a certain packing efficiency threshold.
static java.util.List	getClosestCompositions(CompositionEntry targetComposition, java.util.Collection<CompositionEntry> otherCompositions, int nClosest, int pNorm) Get closest compositions
static org.apache.commons.lang3.tuple.Pair<java.lang.Integer,java.lang.Integer>	getClusterRange(double[] radii, double packingThreshold) Determine the maximum and minimum possible cluster sizes, provided a list of radii.
static double	getIdealRadiusRatio(int NNeighbors) Get the ideal radius ratio for a cluster of a certain size.
java.lang.String	printDescription(boolean htmlFormat) Print out description of attributes.
java.lang.String	printUsage() Print out required format for options.
void	setNNearestToEval(java.util.Collection<java.lang.Integer> toEval) Set the number of nearest clusters to evaluate when computing attributes.
void	setOptions(java.util.List<java.lang.Object> Options) Set any options for this object.
void	setPackingThreshold(double threshold) Define the threshold at which to define a cluster as efficiently packed.
void	setRadiusProperty(java.lang.String property) Set the name of the elemental property used to define radii.

Methods inherited from class magpie.attributes.generators.BaseAttributeGenerator

runCommand

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MaxNTypes

public static int MaxNTypes

Maximum number of types over which to search for clusters. If an alloy has more than this number of elements, the code will only search for clusters with the most prevalent elements

Constructor Detail

APEAttributeGenerator

public APEAttributeGenerator()

Create generator with default settings. Radii are specified using the assessment of Miracle et al. and distances are measured to the first 1, 3, and 5 clusters

Method Detail

setOptions

public void setOptions(java.util.List<java.lang.Object> Options)
                throws java.lang.Exception

Description copied from interface: Options

Set any options for this object. If parsing the options fails, return an Exception with the usage as its message.

Parameters:

Options - Array of options as Objects - can be null

Throws:

java.lang.Exception - if problem with inputs

printUsage

public java.lang.String printUsage()

Description copied from interface: Options

Print out required format for options. For consistency, should start with "Usage: ".

Returns:

Usage for this function

setPackingThreshold

public void setPackingThreshold(double threshold)
                         throws java.lang.Exception

Define the threshold at which to define a cluster as efficiently packed. Packing efficiency is defined as |APE - 1|.

Parameters:

threshold - Desired threshold (default = 0.01)

Throws:

java.lang.Exception

setNNearestToEval

public void setNNearestToEval(java.util.Collection<java.lang.Integer> toEval)

Set the number of nearest clusters to evaluate when computing attributes.

Parameters:

toEval - Collection containing a set of numbers of nearest clusters to evaluate when computing attributes. Default: {1, 3, 5}

setRadiusProperty

public void setRadiusProperty(java.lang.String property)

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.., 2010.

Parameters:

property - Name of property used to define radii

addAttributes

public void addAttributes(Dataset data)
                   throws java.lang.Exception

Description copied from class: BaseAttributeGenerator

Generate new attributes for a dataset. This operation must both add the new attribute names to the dataset and new values to each entry.

Specified by:

addAttributes in class BaseAttributeGenerator

Parameters:

data - Dataset to be added to

Throws:

java.lang.Exception

See Also:

Dataset.addAttribute(java.lang.String, double[])

printDescription

public java.lang.String printDescription(boolean htmlFormat)

Description copied from class: BaseAttributeGenerator

Print out description of attributes.

Implementation Notes

Format should look like

[Full Name of generator]: (Number of attributes) Text description of what these attributes are

For HTML format, omit the ":".

Specified by:

printDescription in class BaseAttributeGenerator

Parameters:

htmlFormat - Whether to print in HTML format

Returns:

Description of the attributes

determineOptimalAPE

public static double determineOptimalAPE(int centralAtomType,
                                         CompositionEntry shellComposition,
                                         double[] radii)

Compute the optimal APE for a cluster with a certain atom type in the center and composition in the cell. 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.

Parameters:

centralAtomType - Element ID (Z - 1) of central atom

shellComposition - Composition of nearest neighbor shell

radii - Lookup table of elemental radii

Returns:

computeClusterCompositions

public static java.util.List<CompositionEntry> computeClusterCompositions(int[] elements,
                                                                          java.util.List<java.util.List<int[]>> clusters)

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:

elements - Elements from which clusters are composed.

clusters - Clusters to convert. List of the identity of shell compositions for each type of central atom. Example: clusters[1][2] Is a array defining the number of atoms of each type for clusters with an atom of type 1 in the center.

Returns:

List of the compositions of these clusters

See Also:

findEfficientlyPackedClusters(double[], double)

findEfficientlyPackedClusters

public static java.util.List<java.util.List<int[]>> findEfficientlyPackedClusters(double[] radii,
                                                                                  double packingThreshold)

Provided a list of atomic radii, find all clusters with better than a certain packing efficiency threshold. The packing efficiency is determined by abs(1 - APE)

Parameters:

radii - Radii of elements

packingThreshold - Desired packing limit threshold. A "default" choice would be 0.05

Returns:

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.

See Also:

computeAPE(double[], int, int[])

computeAPE

public static double computeAPE(double[] radii,
                                int centerType,
                                int[] shellTypes)

Compute the APE of a cluster, provided the identities of the central and 1st neighbor atoms.

Parameters:

radii - Radius of each atom type

centerType - Type of atom in the center

shellTypes - Number of atoms of each type in the outer shell. Must be the same length as radii

Returns:

APE of the cluster

computeAPE

public static double computeAPE(int NNeighbors,
                                double centerRadius,
                                double neighEffRadius)

Compute the APE provided the number of neighbors and radii.

Here, we follow the formulation given by Laws et al., where:
APE = <ideal radius ratio> / (<radius of central atom> / <effective radius of nearest neighbors>)

The ideal ratio is computed using getIdealRadiusRatio(int)

Parameters:

NNeighbors - Number of 1st nearest neighbors in the cluster

centerRadius - Radius of central atom

neighEffRadius - Effective radius of 1st shell. Usually computed as the average radius of all atoms in the shell.

Returns:

APE of the cluster.

getIdealRadiusRatio

public static double getIdealRadiusRatio(int NNeighbors)

Get the ideal radius ratio for a cluster of a certain size.

Note: The ideal radius ratio is only known for clusters with between 3 and 24 (inclusive) neighbors. If you request outside of this range, it will return the value of 3 for anything less than 3, and the value of 24 for anything larger than 24.

Reference: Miracle et al.

Parameters:

NNeighbors - Number of 1st nearest neighbors.

Returns:

Ideal radius ratio

getClusterRange

public static org.apache.commons.lang3.tuple.Pair<java.lang.Integer,java.lang.Integer> getClusterRange(double[] radii,
                                                                                                       double packingThreshold)

Determine the maximum and minimum possible cluster sizes, provided 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 smallest in the outside

Parameters:

radii - List of radii of elements in system

packingThreshold - APE defining the maximum packing threshold

Returns:

Pair. Left: minimum cluster size (defined by number of atoms in shell) . Right: maximum cluster size

getClosestCompositions

public static java.util.List getClosestCompositions(CompositionEntry targetComposition,
                                                    java.util.Collection<CompositionEntry> otherCompositions,
                                                    int nClosest,
                                                    int pNorm)

Get closest compositions

Parameters:

targetComposition - Composition from which to measure distance

otherCompositions - Compositions that whose distance from the target composition will be ranked

nClosest - Number of closest compounds to retrieve

pNorm - P-norm to use when computing distance

Returns:

The