Package _global.tri.oxidationstates.ion

Class IonFactory

java.lang.Object
_global.tri.oxidationstates.ion.IonFactory
public class IonFactory extends Object
This class keeps track of available polyatomic and monatomci ions.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    IonFactory.Ion
    An Ion is a combination of an ion type (e.g.
    static class 
    IonFactory.IonType
    This class represents an ion type, which is an atom (or cluster of atoms) that can be assigned an oxidation state.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IonFactory()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static IonFactory.Ion
    get(String symbol)
    Returns the ion matching the given symbol, or creates a new ion if no such ion exists.
    static IonFactory.Ion
    get(String ionTypeSymbol, double oxidationState)
    Returns an ion corresponding to the given ion type and oxidation state.
    static IonFactory.Ion
    get(matsci.Element element, double oxidationState)
    Returns an ion corresponding to the given element and oxidation state.
    static IonFactory.Ion
    get(matsci.Species species)
    Returns an ion corresponding to the given species.
    static HashMap<String,matsci.structure.Structure>
    getAllKnownRepresentativeStructures(boolean polyatomic)
    Returns a map in which the keys are known ion types and the values are the corresponding representative structures.
    static String
    getIonSymbol(String ionTypeSymbol, double oxidationState)
    Creates a standardized symbol for an ion from an ion type symbol and and oxidation state.
    static String
    getIonTypeSymbol(String ionSymbol)
    Returns the ion type symbol corresponding to the given ion symbol.
    static IonFactory.IonType
    getKnownIonType(String ionTypeSymbol)
    Returns the ion type for the given symbol, or null if no such ion type exists.
    static Map<String,IonFactory.IonType>
    getKnownIonTypes()
    Returns a map in which the keys are the ion type symbols and the values are the corresponding ion types for all known ion types, monatomic and polyatomic.
    static Map<Integer,matsci.structure.Structure>
    getKnownRepresentativeStructures(String ionTypeSymbol)
    Returns a map in which the keys are integer oxidation states and the values are the representative structures for ions of the given ion type with the corresponding oxidation state.
    static double
    getOxidationState(String ionSymbol)
    Returns the oxidation state of the ion with the given ion symbol.
    static String
    getOxidationString(double oxidationState)
    Returns a standardized string representation of the given oxidation state
    static IonFactory.IonType[]
    getPolyatomicTypes()
    Returns an array of known ion types for polyatomic ions.
    static void
    loadPolyatomicIons(String ionTypesDirName)
    Loads into memory the polyatomic ions whose structure files are provided in the given top-level directory.
    protected static boolean
    oxidationCloseEnough(double oxidation1, double oxidation2)
    Returns true if two oxidation states are within a given tolerance, which by default is 0.001.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • IonFactory

      public IonFactory()

  • Method Details

    • get

      public static IonFactory.Ion get(String symbol)
      Returns the ion matching the given symbol, or creates a new ion if no such ion exists. If the ion type for the provided ion is not known, return null. There is only a single ion object for each symbol.
      Parameters:
      symbol - The symbol for the ion to return, including both a structure type symbol and an oxidation state.
      Returns:
      the ion matching the given symbol, or creates a new ion if no such ion exists. If the ion type for the provided ion is not known, return null.

    • get

      public static IonFactory.Ion get(matsci.Species species)
      Returns an ion corresponding to the given species. There is only a single ion object for each species.
      Parameters:
      species - The species for which we want the matching ion.
      Returns:
      the ion corresponding to the given species.

    • get

      public static IonFactory.Ion get(matsci.Element element, double oxidationState)
      Returns an ion corresponding to the given element and oxidation state. There is only a single ion object for each combination of element and oxidation state.
      Parameters:
      element - The element for which we want the ion.
      oxidationState - The oxidation state of the ion.
      Returns:
      an ion corresponding to the given element and oxidation state. There is only a single ion object for each combination of element and oxidation state.

    • get

      public static IonFactory.Ion get(String ionTypeSymbol, double oxidationState)
      Returns an ion corresponding to the given ion type and oxidation state. There is only a single ion object for each combination of element and oxidation state. If no ionType matches the provided symbol, null is returned.
      Parameters:
      ionTypeSymbol - The symbol of the ion type for which we want the ion.
      oxidationState - The oxidation state of the ion.
      Returns:
      an ion corresponding to the given ion type and oxidation state. There is only a single ion object for each combination of element and oxidation state. If no ionType matches the provided symbol, null is returned.

    • getIonSymbol

      public static String getIonSymbol(String ionTypeSymbol, double oxidationState)
      Creates a standardized symbol for an ion from an ion type symbol and and oxidation state.
      Parameters:
      ionTypeSymbol - The symbol for the ion type.
      oxidationState - The oxidation state.
      Returns:
      a standardized symbol for an ion from an ion type symbol and and oxidation state.

    • oxidationCloseEnough

      protected static boolean oxidationCloseEnough(double oxidation1, double oxidation2)
      Returns true if two oxidation states are within a given tolerance, which by default is 0.001. Returns false otherwise.
      Parameters:
      oxidation1 - The first oxidation state to compare
      oxidation2 - The second oxidation state to compare
      Returns:
      true if two oxidation states are within a given tolerance, which by default is 0.001. Returns false otherwise.

    • getIonTypeSymbol

      public static String getIonTypeSymbol(String ionSymbol)
      Returns the ion type symbol corresponding to the given ion symbol.
      Parameters:
      ionSymbol - A symbol for an ion.
      Returns:
      the ion type symbol corresponding to the given ion symbol.

    • getOxidationState

      public static double getOxidationState(String ionSymbol)
      Returns the oxidation state of the ion with the given ion symbol.
      Parameters:
      ionSymbol - A symbol for an ion.
      Returns:
      the oxidation state of the ion with the given ion symbol.

    • getOxidationString

      public static String getOxidationString(double oxidationState)
      Returns a standardized string representation of the given oxidation state
      Parameters:
      oxidationState - An oxidation state
      Returns:
      a standardized string representation of the given oxidation state

    • loadPolyatomicIons

      public static void loadPolyatomicIons(String ionTypesDirName)
      Loads into memory the polyatomic ions whose structure files are provided in the given top-level directory. The top-level directory should contain subdirectories, each of which has a name that matches an ion type. Each of these subdirectories should contain POSCAR-formatted files with a name matching an oxidation state with the extension of ".vasp". The contents of each of these files should be a representation of the structure of the ion with the matching ion type and oxidation state. This method should usually be called near the beginning of the program, before any methods that use polyatomic ions are called, so that those methods have access to the structures of known polyatomic ions. If this method is called more than once on the same top-level directory, then the ions will only be loaded into memory the first time it is called.
      Parameters:
      ionTypesDirName - The top-level directory containing information about polyatomic ion structures. The top-level directory should contain subdirectories, each of which has a name that matches an ion type. Each of these subdirectories should contain POSCAR-formatted files with a name matching an oxidation state with the extension of ".vasp". The contents of each of these files should be a representation of the structure of the ion with the matching ion type and oxidation state.

    • getPolyatomicTypes

      public static IonFactory.IonType[] getPolyatomicTypes()
      Returns an array of known ion types for polyatomic ions.
      Returns:
      an array of known ion types for polyatomic ions.

    • getKnownIonTypes

      public static Map<String,IonFactory.IonType> getKnownIonTypes()
      Returns a map in which the keys are the ion type symbols and the values are the corresponding ion types for all known ion types, monatomic and polyatomic.
      Returns:
      a map in which the keys are the ion type symbols and the values are the corresponding ion types for all known ion types, monatomic and polyatomic.

    • getKnownIonType

      public static IonFactory.IonType getKnownIonType(String ionTypeSymbol)
      Returns the ion type for the given symbol, or null if no such ion type exists.
      Parameters:
      ionTypeSymbol - The symbol for the ion type
      Returns:
      the ion type for the given symbol, or null if no such ion type exists.

    • getKnownRepresentativeStructures

      public static Map<Integer,matsci.structure.Structure> getKnownRepresentativeStructures(String ionTypeSymbol)
      Returns a map in which the keys are integer oxidation states and the values are the representative structures for ions of the given ion type with the corresponding oxidation state. Only integer oxidation states for which the representative structure is known will be included in the returned map.
      Parameters:
      ionTypeSymbol - The symbol for the the ion type.
      Returns:
      a map in which the keys are integer oxidation states and the values are the representative structures for ions of the given ion type with the corresponding oxidation state.

    • getAllKnownRepresentativeStructures

      public static HashMap<String,matsci.structure.Structure> getAllKnownRepresentativeStructures(boolean polyatomic)
      Returns a map in which the keys are known ion types and the values are the corresponding representative structures. This method only returns structures for ions with integer oxidation states.
      Parameters:
      polyatomic - True if only polyatomic ions should be included in the returned map, false if all known ions should be included in the returned map.
      Returns:
      a map in which the keys are known ion types and the values are the corresponding representative structures. This method only returns structures for ions with integer oxidation states.