Package _global.tri.oxidationstates.calculator.likelihood

Class LikelihoodCalculator

java.lang.Object
_global.tri.oxidationstates.calculator.OxidationStateCalculator
_global.tri.oxidationstates.calculator.likelihood.LikelihoodCalculator
public class LikelihoodCalculator extends OxidationStateCalculator
This is the main class for calculating likelihood scores

  • Constructor Details

    • LikelihoodCalculator

      public LikelihoodCalculator(String paramFileName)
      Initialize a likelihood calculator from a parameters file. This is an older constructor; to initialize from a JSON file, use the LikelihoodCalculator(String, boolean) constructor.
      Parameters:
      paramFileName - The name of the parameter file to read

    • LikelihoodCalculator

      public LikelihoodCalculator(String inputFileName, boolean isJSONBoundaryFile)
      Initialize a likelihood calculator from a parameters file.
      Parameters:
      inputFileName - The name of the parameter file
      isJSONBoundaryFile - True if the parameter file is a JSON-formated boundaries file, false if it's a parameters file

    • LikelihoodCalculator

      public LikelihoodCalculator(HashMap<String,int[]> oxidationStateMap)
      Initialized the likelihood calculator from a map of molecule types to allowed oxidation states
      Parameters:
      oxidationStateMap - The map, in which keys are molecule type ids and the values are the allowed oxidation states

  • Method Details

    • hasParamsForIon

      public boolean hasParamsForIon(IonFactory.Ion ion)
      Whether this calculator has parameters for the given ion
      Parameters:
      ion - The given ion
      Returns:
      True if this calculator has parameters for the ion, and false otherwise.

    • hasParamsForIonType

      public boolean hasParamsForIonType(String symbol)
      Whether this calculator has parameters for the given ion type
      Parameters:
      symbol - The symbol for the given ion type
      Returns:
      True if this calculator has parameters for the given ion type, and false otherwise

    • hasParamsForElement

      public boolean hasParamsForElement(matsci.Element element)
      Whether this calculator has parameters for the given element
      Parameters:
      element - The given element
      Returns:
      True if the calculator has parameters for the given element, false otherwise

    • numParameters

      public int numParameters()
      Returns the total number of parameters used by this calculator
      Returns:
      The total number of parameters used by this calculator

    • getParameters

      public double[] getParameters(double[] template)
      Returns the parameters for this calculator
      Parameters:
      template - If this array is provided, the parameters will be copied into it. Otherwise a new array is created.
      Returns:
      The parameters for this calculator.

    • setParameters

      public LikelihoodCalculator setParameters(double[] parameters)
      Returns a new calculator copied with this one, with parameters given by the provided parameters.
      Parameters:
      parameters - The parameters for the new calculator
      Returns:
      A copy of this calculator with the parameters changed to the given parameters.

    • readParameters

      public double[] readParameters(String fileName)
      Read the parameters from a parameters file (the old format, not the JSON format).
      Parameters:
      fileName - The name of the file to be read
      Returns:
      An array of parameters

    • readParametersFromBoundaryJSON

      public double[] readParametersFromBoundaryJSON(String fileName)
      Read parameters from a JSON-formatted boundaries file
      Parameters:
      fileName - The name of the JSON-formatted file
      Returns:
      And array of the read parameters

    • getMinAndMaxBoundary

      public double[] getMinAndMaxBoundary()
      Returns the minimum and maximum boundary values across all ion types
      Returns:
      the minimum and maximum boundary values across all ion types

    • getBoundaries

      public double[] getBoundaries(IonFactory.Ion ion)
      Get the midpoint boundaries (lower and upper) for the given ion
      Parameters:
      ion - The ion for which we want boundaries
      Returns:
      the midpoint boundaries (lower and upper) for the given ion

    • getBoundaries

      public double[] getBoundaries(int ionTypeIndex)
      Return all of the midpoint boundary values for the given ion type
      Parameters:
      ionTypeIndex - The index of the ion type
      Returns:
      all of the midpoint boundary values for the given ion type

    • parametersToBoundaries

      public static double[] parametersToBoundaries(double[] parameters)
      Converts a set of parameters for an ion type into oxidation state boundaries
      Parameters:
      parameters - The parameters for the model
      Returns:
      The oxidation state boundaries for that ion type, ordered from lowest to highest

    • boundariesToParameters

      public static double[] boundariesToParameters(double[] boundaries)
      Converts a set of oxidation state boundaries for an ion type into parameters
      Parameters:
      boundaries - The oxidation state boundaries
      Returns:
      The parameters representing those boundaries, suitable for use in the conjugate gradient optimizer

    • writeBoundaries

      public void writeBoundaries(String fileName)
      Write the boundaries to a simple text file. This will not be the JSON-formatted file.
      Parameters:
      fileName - The name of the file to be written.

    • writeBoundaries

      public void writeBoundaries(OutputStream stream)
      Write the boundaries to an output stream in a simple (non-JSON) format
      Parameters:
      stream - The output stream to which boundaries should be written.

    • writeBoundaryJSON

      public void writeBoundaryJSON(String fileName)
      Write the boundaries to a JSON-formatted file.
      Parameters:
      fileName - The name of the file to be written.

    • writeBoundaryJSON

      public void writeBoundaryJSON(OutputStream stream)
      Write the boundaries in JSON format to an output stream.
      Parameters:
      stream - The output stream to which the bouandaries should be written.

    • writeDataFiles

      public void writeDataFiles(String directoryName, boolean smoothCutoff)
      Write files that can be used to visualize the boundaries
      Parameters:
      directoryName - The name of the directory in which the files should be written.
      smoothCutoff - True if the plots should have smooth boundaries, reflecting the logistic functions, false if the plots should have sharp boundaries.

    • writeDataFiles

      public void writeDataFiles(String directoryName, double lowerBound, double upperBound, double increment, boolean smoothCutoff)
      Write files that can be used to visualize the boundaries
      Parameters:
      directoryName - The name of the directory in which the files should be written.
      lowerBound - The lower electronic chemical potential bound for the plots
      upperBound - The upper electronic chemical potential bound for the plots
      increment - The width of the electronic chemical potential bins used to generate the plots
      smoothCutoff - True if the plots should have smooth boundaries, reflecting the logistic functions, false if the plots should have sharp boundaries.

    • writeDataFile

      public void writeDataFile(String ionType, String fileName, boolean smoothCutoff)
      Write a file that can be used to visualize the boundaries for a particular ion type
      Parameters:
      ionType - The ion type
      fileName - The name of the file to be written
      smoothCutoff - True if the plots should have smooth boundaries, reflecting the logistic functions, false if the plots should have sharp boundaries.

    • writeDataFile

      public void writeDataFile(String ionType, String fileName, double lowerBound, double upperBound, double increment, boolean smoothCutoff)
      Write a file that can be used to visualize the boundaries for a particular ion type
      Parameters:
      ionType - The ion type
      fileName - The name of the file to be written
      lowerBound - The lower electronic chemical potential bound for the plots
      upperBound - The upper electronic chemical potential bound for the plots
      increment - The width of the electronic chemical potential bins used to generate the plots
      smoothCutoff - True if the plots should have smooth boundaries, reflecting the logistic functions, false if the plots should have sharp boundaries.

    • writeParameters

      public void writeParameters(String fileName)
      Write the parameters to a text file (not JSON formatted).
      Parameters:
      fileName - The name of the file to be written.

    • writeParameters

      public void writeParameters(OutputStream stream)
      Write the parameters to an output stream (not JSON formatted).
      Parameters:
      stream - The output stream to which the parameters should be written.

    • getSumOfSpreads

      public double getSumOfSpreads()
      Sum of the maximum boundaries for all ion types, subtract the sum of the minimum boundaries, and report the difference.
      Returns:
      The difference between the sum of the maximum boundaries and the sum of the minimum boundaries.

    • getLikelihood

      public double getLikelihood(double fermiLevel, IonFactory.Ion ion)
      Return the likelihood score for a given ion at a give electronic chemical potential (fermiLevel)
      Parameters:
      fermiLevel - The electronic chemical potential at which to calculate the likelihood score
      ion - The ion for which the likelihood score should be calculated
      Returns:
      the likelihood score for a given ion at a give electronic chemical potential (fermiLevel)

    • optimizeLikelihood

      public LikelihoodCalculator.PotentialOptimizer optimizeLikelihood(matsci.Species[] allSpecies)
      Finds the electronic chemical potential that maximizes the likelihood score for the given set of species
      Parameters:
      allSpecies - The distinct species for which we want to optimize the likelihood score
      Returns:
      the electronic chemical potential that maximizes the likelihood score for the given set of species

    • optimizeLikelihood

      public LikelihoodCalculator.PotentialOptimizer optimizeLikelihood(IonFactory.Ion[] ions)
      Finds the electronic chemical potential that maximizes the likelihood score for the given set of ions
      Parameters:
      ions - The distinct ions for which we want to optimize the likelihood score
      Returns:
      the PotentialOptimizer containing the electronic chemical potential that maximizes the likelihood score for the given set of ions

    • optimizeLikelihood

      public LikelihoodCalculator.PotentialOptimizer optimizeLikelihood(IonFactory.Ion[] ions, double initialFermiLevel)
      Finds the electronic chemical potential that maximizes the likelihood score for the given set of ions
      Parameters:
      ions - The distinct ions for which we want to optimize the likelihood score
      initialFermiLevel - The chemical potential at which we should start the optimization process
      Returns:
      the electronic chemical potential that maximizes the likelihood score for the given set of ions

    • getIonTypeIndex

      public int getIonTypeIndex(String ionTypeSymbol)
      Returns the ion type index (used by this class) for ion types with the given symbol.
      Parameters:
      ionTypeSymbol - The symbol for the ion type
      Returns:
      the ion type index (used by this class) for ion types with the given symbol.

    • getLikelihood

      public double getLikelihood(double fermiLevel, IonFactory.Ion[] allIons)
      Calculates the likelihood score for a given set of ions at a given electronic chemical potential
      Parameters:
      fermiLevel - The given electronic chemical potential
      allIons - The ions for which we are calculating the likelihood score
      Returns:
      the likelihood score for a given set of ions at a given electronic chemical potential

    • optimizeLikelihood

      public LikelihoodCalculator.PotentialOptimizer optimizeLikelihood(OxidationStateData.Entry entry)
      Determine the electronic chemical potential that maximizes the likelihood score for the given entry
      Parameters:
      entry - The entry for which we will maximize the likelihood score
      Returns:
      the electronic chemical potential that maximizes the likelihood score for the given entry

    • optimizeLikelihood

      public LikelihoodCalculator.PotentialOptimizer optimizeLikelihood(String[] ionTypeIDs, double[] weights)
      Determine the electronic chemical potential that maximizes the likelihood score for the given ion type IDS, where weights indicate the composition of each ion type.
      Parameters:
      ionTypeIDs - The ion type IDs for which we are maximizing the likelihood score.
      weights - The compositions of each of the ion type ids, in the same order.
      Returns:
      the electronic chemical potential that maximizes the likelihood score for the given ion type IDS, where weights indicate the composition of each ion type.

    • getAllOxidationStates

      public LikelihoodStateSet[] getAllOxidationStates(String composition, double minAllowedLikelihood, int minNumberToReturn)
      Get all possible oxidation state assignments for the given composition, subject to the given constraints.
      Parameters:
      composition - The composition for which we want oxidation states
      minAllowedLikelihood - The minimum allowed likelihood score for the returned states. Set this to something non-zero to improve performance.
      minNumberToReturn - The minimum number of states to return, even if some of those states have a likelihood score below minAllowedLikelihood
      Returns:
      all possible oxidation state assignments for the given composition, subject to the given constraints.

    • getAllOxidationStates

      public LikelihoodStateSet[] getAllOxidationStates(Composition composition, double minAllowedLikelihood, int minNumberToReturn)
      Returns an array possible oxidation state assignments for the given composition, subject to the given constraints.
      Parameters:
      composition - The composition for which we want oxidation states
      minAllowedLikelihood - The minimum allowed likelihood score for the returned states. Set this to something non-zero to improve performance.
      minNumberToReturn - The minimum number of states to return, even if some of those states have a likelihood score below minAllowedLikelihood
      Returns:
      an array possible oxidation state assignments for the given composition, subject to the given constraints.

    • getMinLikelihoodIndex

      public int getMinLikelihoodIndex(List<LikelihoodStateSet> list)
      Return the index of the state set with the minimum likelihood score from the given list
      Parameters:
      list - The given list
      Returns:
      the index of the state set with the minimum likelihood score from the given list

    • getLikelyOxidationStates

      public LikelihoodStateSet getLikelyOxidationStates(String[] ionTypeIDs, double[] weights)
      Description copied from class: OxidationStateCalculator
      Calculate the most likely oxidation states for the given ion types with the given composition.
      Specified by:
      getLikelyOxidationStates in class OxidationStateCalculator
      Parameters:
      ionTypeIDs - The IDS of the ion types.
      weights - The composition of each ion type, ordered in the way that corresponds to the ordering of ionTypeIDs.
      Returns:
      the most likely oxidation states for the given ion types with the given composition.

    • getKnownOxidationStates

      public IonFactory.Ion[] getKnownOxidationStates()
      Get a an array of all ions known to this calculator
      Returns:
      a an array of all ions known to this calculator

    • getIonTypeSymbol

      public String getIonTypeSymbol(int ionTypeIndex)
      Get the ion type symbol corresponding to the given index
      Parameters:
      ionTypeIndex - The given ion type index
      Returns:
      the ion type symbol corresponding to the given index

    • numIonTypes

      public int numIonTypes()
      Returns the number of ion types known to this calculator
      Returns:
      the number of ion types known to this calculator

    • numOxidationStates

      public int numOxidationStates(int ionTypeIndex)
      Returns the number of oxidation states known to this calculator for the ion type with the given index
      Parameters:
      ionTypeIndex - The given ion type index
      Returns:
      the number of oxidation states known to this calculator for the ion type with the given index

    • getOxidationStates

      public int[] getOxidationStates(String ionTypeSymbol)
      Returns the oxidation states known to this calculator for the ion type with the given symbol
      Parameters:
      ionTypeSymbol - The given symbol
      Returns:
      the oxidation states known to this calculator for the ion type with the given symbol

    • getOxidationState

      public int getOxidationState(int ionTypeIndex, int stateNum)
      Returns the stateNum'th oxidation state for the ion type with the given index
      Parameters:
      ionTypeIndex - The given ion type index
      stateNum - The number of the oxidation state to return
      Returns:
      the stateNum'th oxidation state for the ion type with the given index

    • getParameter

      public double getParameter(int ionTypeIndex, int paramNumForIonType)
      Return the paramNumForMolecule'th parameter for the ion type with the given index
      Parameters:
      ionTypeIndex - The given ion type index
      paramNumForIonType - The parameter number for this ion type
      Returns:
      the paramNumForMolecule'th parameter for the ion type with the given index

    • getParameters

      public double[] getParameters(int ionTypeIndex)
      Returns the parameters for the ion type with the given index
      Parameters:
      ionTypeIndex - The given ion type index
      Returns:
      the parameters for the ion type with the given index