magpie.csp

Class CSPEngine

java.lang.Object

magpie.csp.CSPEngine

All Implemented Interfaces:

Commandable, Options, Printable

Direct Known Subclasses:

CompositionBasedCSPEngine, DMSPEngine

public abstract class CSPEngine
extends java.lang.Object
implements Commandable, Printable, Options

Predict what structure is likely to form at a specific composition from a list of possible candidates.

Usage Guide

To predict the probability that a crystal structure will form:

1. Create an instance of one of the implementations of this class, and set any appropriate options.
2. Import a list of all known compounds, and their prototypes using either the "prototypes" command in the text interface, or importKnownCompounds(java.lang.String)
3. Supply the composition of the compound of interest. Use the "predict" command in the text interface, or predictStructure(java.lang.String) in the Java interface.

Implemented Commands:

exclude <elements...> - Remove entries containing certain elements from the list of known compounds
elements: List of elements abbreviations

get model = $<model> - Get the classifier used to predict last crystal structure

predict <composition> [<# to show>] - Predict what structural prototypes are most likely for a certain compound
composition: Composition of compound of interest
# to show: Number of the top candidates to print (default = 10)

prototypes <filename> - Import list of known prototypes
filename: Path to file containing composition of known compounds, and name of their prototype structure

examples <composition> - Get a list of other possible prototypes for a certain composition and all known examples for each prototype
composition: Composition in question

validate <ncomp> [<folds>] - Evaluate performance of CSP algorithm using cross-validation.
ncomp: Only attempt to predict structures of compounds with this number of constituents
folds: Number of folds in which to split known compounds. Can use "loocv" to perform leave-one-out cross-validation (default = 20)

Implemented Print Commands:

stats - Print out the number of predictions used to generate performance statistics.

stats list-length [<min prob>] [<max length>] - Print out the minimum number of prototypes that need to be calculated for a certain prediction success probability
min prob: Minimum success probability to print (default = 0.7)
max length: Maximum length list to print (default = 20)

Implementation Guide:

In order to create your own crystal structure predictor, you just need to implement a single operation: makeClassifier(PhaseDiagramStatistics, PrototypeDataset) }. This operation generates a classifier that will predict the probability that a certain crystal structure will form given composition. Composition is supplied as a PrototypeEntry where the least-prevalent element is on "A" site, the second least is on the "B", and so on. Any sites with equal fractions are treated as equal (which is a key feature of PrototypeEntry).

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<java.lang.Integer,PhaseDiagramStatistics>	DiagramStatistics Statistics about phase diagrams with certain number of constituents.
protected java.util.Map<CompositionEntry,java.lang.String>	KnownCompounds List of known compounds (used when making predictions)
protected int	LastCompositionBin Matched composition bin of last entry evaluated.
protected int	LastNComponents Number of elements in the last entry evaluated in this class.
protected CSPPerformanceStats	PerformanceStats Holds statistics about CSP algorithm performance.

Constructor Summary

Constructors

Constructor and Description
CSPEngine()

Method Summary

Modifier and Type	Method and Description
java.lang.String	about() Prints a simple status message about this object
void	crossvalidate(int nComp, int folds) Validates predictive ability of this model.
protected void	fillPrototypeEntry(PrototypeEntry entry, int[] siteIdentity) Adjust a PrototypeEntry so that each site is occupied by a specific element
protected java.lang.Object	getComponent(java.lang.String Name) Get a clone of a specific component of this CSP engine.
java.util.List<java.lang.String>	getPossibleStructures(CompositionEntry composition) Get a list of possible structure types for a structure, given composition.
java.util.List<java.lang.String>	getPossibleStructures(java.lang.String composition) Get a list of possible structure types for a structure, given composition.
protected double[]	getProbabilities(BaseClassifier classifier, java.util.List<java.lang.String> knownPrototypes, PrototypeSiteInformation siteInfo, PrototypeEntry entryToPredict) Calculate probability that a compound will form as each of the known prototypes.
PrototypeDataset	getTrainingSet(CompositionEntry composition) Get a training set of all examples of all possible crystal structures at a certain composition
void	importKnownCompounds(java.lang.String filename) Gather a list of known compounds an their prototypes.
protected abstract BaseClassifier	makeClassifier(PhaseDiagramStatistics statistics, PrototypeDataset trainData) Given the dataset of training examples, make a classifier to predict the probability that a prototype will form at a certain composition.
protected PrototypeSiteInformation	makeSiteInfo(double[] fracs) Generate PrototypeSiteInformation appropriate for a certain crystal prototype.
java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,java.lang.Double>>	predictStructure(CompositionEntry composition) Predict what structure is most likely at a certain composition
java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,java.lang.Double>>	predictStructure(java.lang.String Composition) Predict what structure is most likely at a certain composition
java.lang.String	printCommand(java.util.List<java.lang.String> Command) Handles more complicated printing commands.
java.lang.String	printDescription(boolean htmlFormat) Print full name of object, and a simple description of the options.
void	removeKnownCompoundsContainingElements(java.util.List<java.lang.String> ElementList) Given a list of elements, remove all entries that contain those elements from the list of known compounds.
java.lang.Object	runCommand(java.util.List<java.lang.Object> Command) Process some command described by a list of Objects.
void	setKnownCompounds(java.util.Map<CompositionEntry,java.lang.String> KnownCompounds) Define the composition and prototype of already-known compounds.

Methods inherited from class java.lang.Object

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

Methods inherited from interface magpie.utility.interfaces.Options

printUsage, setOptions

Field Detail

KnownCompounds

protected java.util.Map<CompositionEntry,java.lang.String> KnownCompounds

List of known compounds (used when making predictions)

DiagramStatistics

protected java.util.Map<java.lang.Integer,PhaseDiagramStatistics> DiagramStatistics

Statistics about phase diagrams with certain number of constituents. Holds information about the structure of compounds that forms at each composition

LastNComponents

protected int LastNComponents

Number of elements in the last entry evaluated in this class. Used to determine whether we classifier needs to be reset.

LastCompositionBin

protected int LastCompositionBin

Matched composition bin of last entry evaluated.

PerformanceStats

protected CSPPerformanceStats PerformanceStats

Holds statistics about CSP algorithm performance.

Constructor Detail

CSPEngine

public CSPEngine()

Method Detail

importKnownCompounds

public void importKnownCompounds(java.lang.String filename)

Gather a list of known compounds an their prototypes. Format:

<compound #1 composition>[tab]<compound #1 prototype>
<compound #2 composition>[tab]<compound #2 prototype>
[...]

Parameters:

filename - Path to compound data file

setKnownCompounds

public void setKnownCompounds(java.util.Map<CompositionEntry,java.lang.String> KnownCompounds)

Define the composition and prototype of already-known compounds.

Parameters:

KnownCompounds - Map of a compound's composition to the name of its prototype

removeKnownCompoundsContainingElements

public void removeKnownCompoundsContainingElements(java.util.List<java.lang.String> ElementList)

Given a list of elements, remove all entries that contain those elements from the list of known compounds.

Parameters:

ElementList - List of elements to be removed

getPossibleStructures

public java.util.List<java.lang.String> getPossibleStructures(java.lang.String composition)
                                                       throws java.lang.Exception

Get a list of possible structure types for a structure, given composition.

Parameters:

composition - Composition of structure in question

Returns:

List of names of possible prototypes

Throws:

java.lang.Exception

getPossibleStructures

public java.util.List<java.lang.String> getPossibleStructures(CompositionEntry composition)

Get a list of possible structure types for a structure, given composition.

Parameters:

composition - Composition of structure in question

Returns:

List of names of possible prototypes

getTrainingSet

public PrototypeDataset getTrainingSet(CompositionEntry composition)

Get a training set of all examples of all possible crystal structures at a certain composition

Parameters:

composition - Composition of interest

Returns:

Training set

predictStructure

public java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,java.lang.Double>> predictStructure(java.lang.String Composition)
                                                                                                        throws java.lang.Exception

Predict what structure is most likely at a certain composition

Parameters:

Composition - Composition to be evaluated

Returns:

List of names of prototypes and their probabilities

Throws:

java.lang.Exception - If Composition does not parse correctly

predictStructure

public java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,java.lang.Double>> predictStructure(CompositionEntry composition)

Predict what structure is most likely at a certain composition

Parameters:

composition - Composition to be evaluated

Returns:

List of names of prototypes and their probabilities

makeSiteInfo

protected PrototypeSiteInformation makeSiteInfo(double[] fracs)

Generate PrototypeSiteInformation appropriate for a certain crystal prototype. Assumes any sites with the same fraction are equivalent

Parameters:

fracs - Fractions of elements on each site. Sorted in ascending order

Returns:

Appropriate PrototypeSiteInformation

getProbabilities

protected double[] getProbabilities(BaseClassifier classifier,
                                    java.util.List<java.lang.String> knownPrototypes,
                                    PrototypeSiteInformation siteInfo,
                                    PrototypeEntry entryToPredict)

Calculate probability that a compound will form as each of the known prototypes.

Parameters:

classifier - Model trained to predict which prototype will form, given composition.

knownPrototypes - List of known prototypes

siteInfo - Information about the prototypes

entryToPredict - Entry to predict

Returns:

List of probabilities (that add to 1) in same order as knownPrototypes

makeClassifier

protected abstract BaseClassifier makeClassifier(PhaseDiagramStatistics statistics,
                                                 PrototypeDataset trainData)

Given the dataset of training examples, make a classifier to predict the probability that a prototype will form at a certain composition.

Parameters:

statistics - Statistics about all known phase diagrams (could be used predictively)

trainData - Training data, where each entry maps

Returns:

Classifier fitting the specifications above

fillPrototypeEntry

protected void fillPrototypeEntry(PrototypeEntry entry,
                                  int[] siteIdentity)

Adjust a PrototypeEntry so that each site is occupied by a specific element

Parameters:

entry - Entry to be modified

siteIdentity - Identity of element present on each site.

crossvalidate

public void crossvalidate(int nComp,
                          int folds)

Validates predictive ability of this model. Works by segmenting list of known compounds with a certain number of constituents into folds different subsets. Then, the CSP algorithm is used to predict which compound will form for each compound in one of subsets given all of the known compounds in the remaining folds - 1. This process is then repeated for each other subset. Any compound that has a different number of compounds is always kept

Note: If a compound in the testing set has a prototype that is not present in the remaining subsets, no attempt is made to predict its structure. The number of times this occurs will be recorded.

Parameters:

nComp - Only attempt to predict structures of compounds with these many elements

folds - Number of folds to use (if ≤0, preform leave-one-out cross-validation)

runCommand

public java.lang.Object runCommand(java.util.List<java.lang.Object> Command)
                            throws java.lang.Exception

Description copied from interface: Commandable

Process some command described by a list of Objects.

Specified by:

runCommand in interface Commandable

Parameters:

Command - Command as a list of objects

Returns:

Any output (null if no output generated by command)

Throws:

java.lang.Exception - If something goes wrong

about

public java.lang.String about()

Description copied from interface: Printable

Prints a simple status message about this object

Specified by:

about in interface Printable

Returns:

Short status message

printDescription

public java.lang.String printDescription(boolean htmlFormat)

Description copied from interface: Printable

Print full name of object, and a simple description of the options. This description should print enough information to reproduce how this object was created, but not necessarily enough to run it (e.g., coefficients for the model).

Example: For a model training a separate WekaRegression for intermetallics

magpie.models.regression.SplitRegression

Splitter: AllMetalsSplitter
All Metals: magpie.models.regression.WekaRegression trees.REPTree
Contains Nonmetal: magpie.regression.LASSORegreession -maxterms 2

Specified by:

printDescription in interface Printable

Parameters:

htmlFormat - Whether format for output to an HTML page (e.g., <div> to create indentation) or for printing to screen.

Returns:

String describing the model

See Also:

#printModel()

printCommand

public java.lang.String printCommand(java.util.List<java.lang.String> Command)
                              throws java.lang.Exception

Description copied from interface: Printable

Handles more complicated printing commands.

Specified by:

printCommand in interface Printable

Parameters:

Command - Command specifying what to print

Returns:

String formatted as requested

Throws:

java.lang.Exception - If command not understood

getComponent

protected java.lang.Object getComponent(java.lang.String Name)
                                 throws java.lang.Exception

Get a clone of a specific component of this CSP engine.

Parameters:

Name - Name of component

Returns:

Clone if that component

Throws:

java.lang.Exception - For various reasons (see text)