PhaseDiagramStatistics (magpie API)

java.lang.Object
- magpie.csp.diagramdata.PhaseDiagramStatistics

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

OnTheFlyPhaseDiagramStatistics
```
public abstract class PhaseDiagramStatistics
extends java.lang.Object
implements java.io.Serializable
```
Holds what compounds exist in phase diagrams. Can be used to calculate the probability of certain compound having certain characteristics depending on what elements are at specific compositions in its corresponding phase diagram. Based on work by Fisher et al.
Practical Guide:
Disregarding actually informing you what is being computed. Use this class by:
1. For a list of compounds, calculate whether your desired condition is true for each entry
2. Train the cumulant functions by calling getCumulants(PrototypeDataset, boolean[]) }
3. Use those functions predictively by calling evaluateProbability(PrototypeEntry, double[][], double)
Theory Behind this Method:
The simple goal of this method is to calculate correlations between two events, like a phase diagram having a B2 compound and one of its constituents being Fe. This is accomplished by representing each phase diagram by the following variable vector:
C₁, ..., C_N, E₁, ..., E_N where C_i is the identity of a certain (numbered) prototype compound existing near composition bin i and E_j is the identity of element j in the phase diagram.
With this description, one can calculate the probability of some condition being true for a compound in a certain phase diagram by calculating:
P(condition | C₁ = a₁ ∩ ... ∩ E_N = Z_N) where a_i is the identity of the structure of the compound that exists at composition C_i of the phase diagram. Similarly, Z_i is the atomic number of the i-th constituent of the phase diagram.
In order make this computable, Fisher et al used the following approximation (known as the Morita cumulant expansion):
P(a ∩ b ∩ c ∩ ...) = 1 / Z * P(a) * P(b) * [...] * g(a,b) * g(a,c) * [...] where g(a,b) = P(a ∩ b) / P(a) / P(b).
Applied to the above condition probability formula, this allows the following simplification:
P(condition | C₁ = a₁ ∩ ... ∩ E_N = Z_N) = P(condition ∩ C₁ = a₁ ∩ ...) / P(condition) / P(C₁ = a₁ ∩ ...)
≈ P(condition) * g(condition, C₁ = a₁) * [...]
All of the probabilities necessary to calculate are relatively straightforward to compute. The only other important thing to note is a slight adjustment to the calculated probabilities that ensures that P(x ∩ y) is always non-zero, but is always some small positive value. This (very clever) modification allows for P(condition | ...) to be non-zero when the condition and only one of the variables have not yet been observed to exist together before. Otherwise, the corresponding g(x,y) will be zero and the calculated probability would be zero - even if all other variables have favorable correlations.
g(condition, x==y) = P(condition ∩ x) / P(stable) / P(x==y)
P(stable) is: ([# condition == true] + 1 / [# training examples]) / [# examples]
P(x==y) is: ([# times condition x==y in all phase diagrams] + 1 / [# of possible values for x]) / [# of phase diagrams]
P(stable ∩ x) is: ([# times both were true] + 1 / [# possible values] / [# examples]) / [# of examples]
Implementation Guide:
Every operation necessary for this class except three are implemented in the base class. In order to make a functioning version, one needs to implement:
1. processCompounds(java.util.Map) - Given a map of compound compositions and a name of their prototype, save the compound's location in a phase diagram and the prototype as a possible candidate structure at a certain composition.
2. getCompoundVector(int[]) - Given the identity of an element on each site of a crystal, return a list of the identity of each structure at each of the CommonCompositions (0 for no compound).
3. calculateStructureProbabilities() - Calculate the probability of each prototype existing at each composition in CommonCompositions. Note the revised method for calculating probabilities (see "Theory Behind this Method").
See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.List<org.apache.commons.lang3.tuple.Pair<double[],java.util.List<java.lang.String>>>`	`CommonCompositions` List of common compositions and the names of prototypes found at that composition.
`protected java.util.Comparator<org.apache.commons.lang3.tuple.Pair<double[],java.util.List<java.lang.String>>>`	`CompositionComparator` Used to sort CommonCompositions.
`protected double`	`ElementProbability` Probability that each element appears in a phase diagram
`protected double`	`MinDistance` Minimum Manhattan distance between compositions to be considered equal
`protected int`	`NComponents` Order of phase diagram
`protected int`	`NCompounds` Number compounds stored by this object
`protected double[][]`	`StructureProbability` For each composition, probability of each structure existing in a phase diagram.

Constructor Summary

Constructors
Modifier Constructor and Description

protected PhaseDiagramStatistics()
Create a blank instance of this class.

Constructors
Modifier	Constructor and Description
`protected`	`PhaseDiagramStatistics()` Create a blank instance of this class.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addCompositionBin(double[] x, java.util.List<java.lang.String> Prototypes)` Adds all permutations (i.e.
`protected void`	`calculateProbabilities()` Calculate the probability of each compound and element being in a phase diagram.
`protected abstract void`	`calculateStructureProbabilities()` Calculate the probability of each prototype appearing in a phase diagram.
`protected boolean`	`compositionsAreEqual(double[] a, double[] b)` Determine whether two compositions are equal (within MinDistance).
`double[]`	`createLookupKey(double[] frac)` Extend the length of a composition by padding the end with zeros.
`double`	`evaluateProbability(PrototypeEntry entry, double[][] cumulant, double conditionProb)` Given a prototype entry, generate its probability of having a certain condition.
`int`	`getClosestBin(double[] key)` Find the composition bin in CommonCompositions) that has the same number of elements and is the closest
`protected void`	`getCommonCompositions(java.util.Map<CompositionEntry,java.lang.String> Compounds, int[] DesiredNBins)` Determine most common compositions from all structures.
`protected abstract int[]`	`getCompoundVector(int[] sites)` Given a list of elements on each site of a structure, determine which prototypes exist on each site of the corresponding phase diagram.
`double[][]`	`getCumulants(PrototypeDataset trainingData, boolean[] hasCondition)` For a certain training set, calculate the cumulant function between a condition being true and each variable being any allowed condition.
`java.util.List<java.lang.String>`	`getPrototypeNames(double[] fracs)` Get list of all known prototype structures at a composition.
`int[]`	`getVariableVector(PrototypeEntry compound)` For a certain prototype, get a vector that describes the characteristics of its phase diagram.
`protected java.util.Map<CompositionEntry,java.lang.String>`	`importCompoundDataset(java.lang.String filename)` Load in file containing composition and prototypes of all known compounds.
`void`	`importKnownCompounds(java.util.Map<CompositionEntry,java.lang.String> compounds, int DiagramOrder, int[] DesiredNBins)` Import list of known compounds into phase diagram object
`void`	`importKnownCompounds(java.lang.String Filename, int DiagramOrder, int[] DesiredNBins)` Import all known compounds into phase diagram object
`int`	`NComponents()` Get the order of the phase diagram (number of elements).
`int`	`NCompositions()`
`int`	`NCompounds()` Get number of compounds stored by this object.
`static void`	`orderComposition(int[] elems, double[] frac)` Ensure that a composition is sorted such that elements are listed in ascending order by atomic fraction
`java.lang.String`	`printCumulants(double[][] cumulants, int toPrint)` Print out values of each cumulant and their names.
`protected abstract void`	`processCompounds(java.util.Map<CompositionEntry,java.lang.String> compounds)` Given a list of compounds, mark which phase diagrams they appear in.
`int`	`roundComposition(double[] frac)` Round a compound such that it's composition exactly equals that of a common composition, and return the index of that composition

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MinDistance
```
protected final double MinDistance
```
    Minimum Manhattan distance between compositions to be considered equal
    
    See Also:
    
    Constant Field Values
  - NComponents
```
protected int NComponents
```
    Order of phase diagram
  - ElementProbability
```
protected double ElementProbability
```
    Probability that each element appears in a phase diagram
  - CommonCompositions
```
protected java.util.List<org.apache.commons.lang3.tuple.Pair<double[],java.util.List<java.lang.String>>> CommonCompositions
```
    List of common compositions and the names of prototypes found at that composition. Compositions with identical stoichiometry (i.e. AB and BA) share the same list. Key of the pair is an array where [0] is the number of elements, and the other entries are the stoichiometries (ex:, A3B -> [0.75,0.25]) Value is the names prototypes observed at that stoichiometries
  - StructureProbability
```
protected double[][] StructureProbability
```
    For each composition, probability of each structure existing in a phase diagram. [][0] is the no-structure condition.
  - CompositionComparator
```
protected final java.util.Comparator<org.apache.commons.lang3.tuple.Pair<double[],java.util.List<java.lang.String>>> CompositionComparator
```
    Used to sort CommonCompositions. Only sorts by the composition, never the list of prototype names.
  - NCompounds
```
protected int NCompounds
```
    Number compounds stored by this object
- Constructor Detail
  - PhaseDiagramStatistics
```
protected PhaseDiagramStatistics()
```
    Create a blank instance of this class.
- Method Detail
  - orderComposition
```
public static void orderComposition(int[] elems,
                                    double[] frac)
```
    Ensure that a composition is sorted such that elements are listed in ascending order by atomic fraction
    
    Parameters:
    
    elems - Elements present in sample
    
    frac - Fractions of each element present
  - NCompounds
```
public int NCompounds()
```
    Get number of compounds stored by this object.
    
    Returns:
    
    Number of distinct compounds stored by this object.
  - NComponents
```
public int NComponents()
```
    Get the order of the phase diagram (number of elements).
    
    Returns:
    
    Number of elements in each phase diagram
  - compositionsAreEqual
```
protected boolean compositionsAreEqual(double[] a,
                                       double[] b)
```
    Determine whether two compositions are equal (within MinDistance). Uses the Manhattan distance.
    
    Parameters:
    
    a - Composition #1
    
    b - Composition #2
    
    Returns:
    
    Whether they are closer than a minimum tolerance
  - getVariableVector
```
public int[] getVariableVector(PrototypeEntry compound)
```
    For a certain prototype, get a vector that describes the characteristics of its phase diagram. This variable vector has the following entries: S₁, [...,] S_N, E₁, [...,] E_C where S_i is the identity of the structure in composition bin i (0 for no compound) and E_j is the identity of element on site j.
    
    Parameters:
    
    compound - Compound of interest
    
    Returns:
    
    Vector describing phase diagram
  - calculateProbabilities
```
protected void calculateProbabilities()
```
    Calculate the probability of each compound and element being in a phase diagram. It only needs to be done once.
  - importKnownCompounds
```
public void importKnownCompounds(java.lang.String Filename,
                                 int DiagramOrder,
                                 int[] DesiredNBins)
```
    Import all known compounds into phase diagram object
    
    Parameters:
    
    Filename - Path to a file containing all known compounds
    
    DiagramOrder - Number of constituents in phase diagram (2 for binary, etc)
    
    DesiredNBins - Number of composition bins for each number of compounds. Should be an array where x[i] is the number of desired composition bins for compositions with i+1 components.
  - importKnownCompounds
```
public void importKnownCompounds(java.util.Map<CompositionEntry,java.lang.String> compounds,
                                 int DiagramOrder,
                                 int[] DesiredNBins)
```
    Import list of known compounds into phase diagram object
    
    Parameters:
    
    compounds - Map of composition to prototype name
    
    DiagramOrder - Number of constituents in phase diagram (2 for binary, etc)
    
    DesiredNBins - Number of composition bins for each number of compounds. Should be an array where x[i] is the number of desired composition bins for compositions with i+1 components.
  - calculateStructureProbabilities
```
protected abstract void calculateStructureProbabilities()
```
    Calculate the probability of each prototype appearing in a phase diagram.
  - importCompoundDataset
```
protected java.util.Map<CompositionEntry,java.lang.String> importCompoundDataset(java.lang.String filename)
```
    Load in file containing composition and prototypes of all known compounds.
    
    Parameters:
    
    filename - Path to data file
    
    Returns:
    
    Map of composition to structural prototype
  - NCompositions
```
public int NCompositions()
```
    Returns:
    
    Number of different compositions bins
  - getCommonCompositions
```
protected void getCommonCompositions(java.util.Map<CompositionEntry,java.lang.String> Compounds,
                                     int[] DesiredNBins)
```
    Determine most common compositions from all structures. Does so by first finding most common stoichiometry and then storing all permutations (AB, BA, ABC, BAC, ...).
    
    Parameters:
    
    Compounds - Map of compound compositions and prototype names
    
    DesiredNBins - Number of composition bins to have for each number of constituents. x[0] is for binaries, x[1] for ternaries, and so on...
  - addCompositionBin
```
protected void addCompositionBin(double[] x,
                                 java.util.List<java.lang.String> Prototypes)
```
    Adds all permutations (i.e. ABC, BAC, ...) to
    
    Parameters:
    
    x - Stoichiometry to be added (must be sorted in ascending order)
    
    Prototypes - List that holds names of all prototypes with this stoichiometry (does not have to contain anything yet)
  - getCumulants
```
public double[][] getCumulants(PrototypeDataset trainingData,
                               boolean[] hasCondition)
```
    For a certain training set, calculate the cumulant function between a condition being true and each variable being any allowed condition. Each variable, and their possible values are described in getVariableVector(PrototypeEntry)
    
    Parameters:
    
    trainingData - Data containing examples on which to train cumulant functions
    
    hasCondition - For each entry in the training set, whether whatever condition is true
    
    Returns:
    
    x[i][j] is the cumulant function: g(condition == True, variable_i == j)
  - evaluateProbability
```
public double evaluateProbability(PrototypeEntry entry,
                                  double[][] cumulant,
                                  double conditionProb)
```
    Given a prototype entry, generate its probability of having a certain condition. For prototypes that have symmetrically-equivalent sites, this operation will calcualate the maximum probability for all equivalent arrangements.
    
    Parameters:
    
    entry - Entry to evaluate
    
    cumulant - Cumulant function values generated by getCumulants(PrototypeDataset, boolean[])
    
    conditionProb - Probability that a random entry has the condition
    
    Returns:
    
    Probability of this particular entry having a condition
  - getCompoundVector
```
protected abstract int[] getCompoundVector(int[] sites)
```
    Given a list of elements on each site of a structure, determine which prototypes exist on each site of the corresponding phase diagram.
    
    Parameters:
    
    sites - Which elements are on each site
    
    Returns:
    
    x[i] is the index of the prototype structure of the compound existing at composition i in CommonCompositions (0 for no compound)
  - processCompounds
```
protected abstract void processCompounds(java.util.Map<CompositionEntry,java.lang.String> compounds)
```
    Given a list of compounds, mark which phase diagrams they appear in. Also, keep a list of the names of prototype compounds that appear
    
    Parameters:
    
    compounds - Map of phase diagrams to be added
  - getClosestBin
```
public int getClosestBin(double[] key)
```
    Find the composition bin in CommonCompositions) that has the same number of elements and is the closest
    
    Parameters:
    
    key - Composition of a compound. Defined by the fraction of each element present, first element is the number of elements, the remainder is the fraction of each element
    
    Returns:
    
    Index of bin closest to this composition
  - createLookupKey
```
public double[] createLookupKey(double[] frac)
```
    Extend the length of a composition by padding the end with zeros.
    
    Parameters:
    
    frac - Fraction to be extend
    
    Returns:
    
    frac extended with 0s
  - printCumulants
```
public java.lang.String printCumulants(double[][] cumulants,
                                       int toPrint)
```
    Print out values of each cumulant and their names. Prints only the ones with the strongest effect on the calculated probability. This is measured by |log(cumulant)|
    
    Parameters:
    
    cumulants - Cumulants to be printed
    
    toPrint - Number of the strongest cumulants to print. -1 for all of them
    
    Returns:
    
    List containing the top toPrint cumulants
  - roundComposition
```
public int roundComposition(double[] frac)
```
    Round a compound such that it's composition exactly equals that of a common composition, and return the index of that composition
    
    Parameters:
    
    frac - Atomic fractions of elements in the compound (will be rounded to match that of the closest bin)
    
    Returns:
    
    Index of compound prototype in the list prototypes known at the nearest composition
  - getPrototypeNames
```
public java.util.List<java.lang.String> getPrototypeNames(double[] fracs)
```
    Get list of all known prototype structures at a composition.
    
    Parameters:
    
    fracs - Fraction of elements in
    
    Returns:
    
    List of prototype names at the closest bin to composition

Class PhaseDiagramStatistics

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MinDistance

NComponents

ElementProbability

CommonCompositions

StructureProbability

CompositionComparator

NCompounds

Constructor Detail

PhaseDiagramStatistics

Method Detail

orderComposition

NCompounds

NComponents

compositionsAreEqual

getVariableVector

calculateProbabilities

importKnownCompounds

importKnownCompounds

calculateStructureProbabilities

importCompoundDataset

NCompositions

getCommonCompositions

addCompositionBin

getCumulants

evaluateProbability

getCompoundVector

processCompounds

getClosestBin

createLookupKey

printCumulants

roundComposition

getPrototypeNames