Package ffx.potential.utils

Interface PotentialsFunctions

All Known Subinterfaces:
AlgorithmFunctions
All Known Implementing Classes:
AlgorithmUtils, PotentialsUtils, UIUtils
public interface PotentialsFunctions
PotentialsFunctions describes core functionality for many Force Field X algorithms and scripts, such as opening and closing structure files, basic force field energy evaluations, etc.

This is implemented in two locations: UIUtils in the User Interfaces package, and in PotentialsUtils in the Potentials package.

The UIUtils implementation is the default for Force Field X; on top of the core functionality, it also updates the FFX graphical user interface and tree structure.

The PotentialsUtils implementation lacks the extra functionality of the UIUtils implementation, and simply accomplishes the required task. This is used by our tests, and is also potentially useful for third parties who would like to use FFX without its GUI.

Since:
1.0
Author:
Jacob M. Litman, Michael J. Schnieders

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Logger
    logger
    Constant logger

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close(MolecularAssembly assembly)
    Performs any necessary shutdown operations on a MolecularAssembly, primarily shutting down Parallel Java threads and closing any other open resources.
    void
    closeAll(MolecularAssembly[] assemblies)
    Performs any necessary shutdown operations on an array of MolecularAssembly, primarily shutting down Parallel Java threads and closing any other open resources.
    ForceFieldEnergy
    energy(MolecularAssembly assembly)
    Evaluates the energy of a MolecularAssembly and returns its ForceFieldEnergy object.
    ForceFieldEnergy[]
    energy(MolecularAssembly[] molecularAssemblies)
    Evaluates the energy of each MolecularAssembly and returns their ForceFieldEnergy instances.
    default MolecularAssembly
    getActiveAssembly()
    Returns either the active assembly from the overlying UI, or the "active" molecular assembly from the last used SystemFilter.
    default List<String>
    getArguments()
    If available, returns CLI arguments; default implementation does not have access to CLI arguments, and throws UnsupportedOperationException.
    SystemFilter
    getFilter()
    Returns the last SystemFilter created by this (can be null).
    boolean
    isLocal()
    True if using a local implementation (not in a user interfaces module).
    default MolecularAssembly
    open(String filename)
    open.
    default MolecularAssembly[]
    open(String[] files, int nThreads)
    Opens an array of files and returns all created MolecularAssembly objects, setting any underlying Potential to use a certain number of threads.
    MolecularAssembly[]
    openAll(String file)
    Opens a file and returns all created MolecularAssembly objects.
    MolecularAssembly[]
    openAll(String[] files)
    Opens an array of files and returns the created MolecularAssembly objects.
    default MolecularAssembly[]
    openAll(String file, int nThreads)
    Opens a file and returns all created MolecularAssembly objects, setting any underlying Potential to use a certain number of threads.
    double
    returnEnergy(MolecularAssembly assembly)
    Returns the energy of a MolecularAssembly in kcal/mol (as a double) and prints the energy evaluation
    void
    save(MolecularAssembly assembly, File file)
    Saves the current state of a MolecularAssembly to an XYZ file.
    void
    saveAsPDB(MolecularAssembly[] assemblies, File file)
    Saves the current state of an array of MolecularAssembly instances to a PDB file.
    void
    saveAsPDB(MolecularAssembly assembly, File file)
    Saves the current state of a MolecularAssembly to a PDB file.
    void
    saveAsPDB(MolecularAssembly assembly, File file, boolean writeEnd, boolean append)
     
    void
    saveAsPDBinP1(MolecularAssembly assembly, File file)
    Saves the symmetry mates of a MolecularAssembly to PDB files.
    void
    saveAsXYZ(MolecularAssembly assembly, File file)
    Saves the current state of a MolecularAssembly to an XYZ file.
    void
    saveAsXYZasReplicates(MolecularAssembly assembly, File file, int[] replicatesVector)
    Saves the current state of a MolecularAssembly to an XYZ file as a replicates crystal.
    void
    saveAsXYZinP1(MolecularAssembly assembly, File file)
    Saves the current state of a MolecularAssembly to an XYZ file as a P1 crystal.
    double
    time()
    Logs time elapsed since last call.
    default File
    versionFile(File file)
    Versions a file, attempting to find an unused filename in the set filename, and filename_1 to filename_999.
    default String
    versionFile(String filename)
    Versions a file, attempting to find an unused filename in the set filename, and filename_1 to filename_999.

  • Field Details

    • logger

      static final Logger logger
      Constant logger

  • Method Details

    • close

      void close(MolecularAssembly assembly)
      Performs any necessary shutdown operations on a MolecularAssembly, primarily shutting down Parallel Java threads and closing any other open resources.
      Parameters:
      assembly - Assembly to close.

    • closeAll

      void closeAll(MolecularAssembly[] assemblies)
      Performs any necessary shutdown operations on an array of MolecularAssembly, primarily shutting down Parallel Java threads and closing any other open resources.
      Parameters:
      assemblies - Assemblies to close.

    • energy

      ForceFieldEnergy energy(MolecularAssembly assembly)
      Evaluates the energy of a MolecularAssembly and returns its ForceFieldEnergy object.
      Parameters:
      assembly - To evaluate
      Returns:
      assembly's ForceFieldEnergy.

    • energy

      ForceFieldEnergy[] energy(MolecularAssembly[] molecularAssemblies)
      Evaluates the energy of each MolecularAssembly and returns their ForceFieldEnergy instances.
      Parameters:
      molecularAssemblies - An array of molecularAssembly instances.
      Returns:
      An array of ForceFieldEnergy instances.

    • getActiveAssembly

      default MolecularAssembly getActiveAssembly()
      Returns either the active assembly from the overlying UI, or the "active" molecular assembly from the last used SystemFilter.
      Returns:
      A MolecularAssembly or null

    • getArguments

      default List<String> getArguments() throws UnsupportedOperationException
      If available, returns CLI arguments; default implementation does not have access to CLI arguments, and throws UnsupportedOperationException.
      Returns:
      CLI arguments
      Throws:
      UnsupportedOperationException - If unimplemented
      UnsupportedOperationException - if any.

    • getFilter

      SystemFilter getFilter()
      Returns the last SystemFilter created by this (can be null).
      Returns:
      Last SystemFilter

    • isLocal

      boolean isLocal()
      True if using a local implementation (not in a user interfaces module).
      Returns:
      If a local implementation

    • open

      default MolecularAssembly open(String filename)
      open.
      Parameters:
      filename - a String object.
      Returns:
      a MolecularAssembly object.

    • open

      default MolecularAssembly[] open(String[] files, int nThreads)
      Opens an array of files and returns all created MolecularAssembly objects, setting any underlying Potential to use a certain number of threads. Default implementation simply ignores nThreads.
      Parameters:
      files - an array of String objects.
      nThreads - Use non-default num threads
      Returns:
      Array of MolecularAssembly.

    • openAll

      MolecularAssembly[] openAll(String file)
      Opens a file and returns all created MolecularAssembly objects.
      Parameters:
      file - Filename to open
      Returns:
      Array of MolecularAssembly.

    • openAll

      MolecularAssembly[] openAll(String[] files)
      Opens an array of files and returns the created MolecularAssembly objects.
      Parameters:
      files - Filenames to open.
      Returns:
      Array of MolecularAssembly.

    • openAll

      default MolecularAssembly[] openAll(String file, int nThreads)
      Opens a file and returns all created MolecularAssembly objects, setting any underlying Potential to use a certain number of threads. Default implementation simply ignores nThreads.
      Parameters:
      file - Filename to open
      nThreads - Use non-default num threads
      Returns:
      Array of MolecularAssembly.

    • returnEnergy

      double returnEnergy(MolecularAssembly assembly)
      Returns the energy of a MolecularAssembly in kcal/mol (as a double) and prints the energy evaluation
      Parameters:
      assembly - To evaluate energy of
      Returns:
      Potential energy (kcal/mol)

    • save

      void save(MolecularAssembly assembly, File file)
      Saves the current state of a MolecularAssembly to an XYZ file.
      Parameters:
      assembly - MolecularAssembly to save
      file - Destination .xyz

    • saveAsXYZinP1

      void saveAsXYZinP1(MolecularAssembly assembly, File file)
      Saves the current state of a MolecularAssembly to an XYZ file as a P1 crystal.
      Parameters:
      assembly - MolecularAssembly to save
      file - Destination .xyz

    • saveAsXYZasReplicates

      void saveAsXYZasReplicates(MolecularAssembly assembly, File file, int[] replicatesVector)
      Saves the current state of a MolecularAssembly to an XYZ file as a replicates crystal.
      Parameters:
      assembly - MolecularAssembly to save
      file - Destination .xyz
      replicatesVector - Dimensions for replicates crystal.

    • saveAsPDB

      void saveAsPDB(MolecularAssembly assembly, File file)
      Saves the current state of a MolecularAssembly to a PDB file.
      Parameters:
      assembly - MolecularAssembly to save
      file - Destination .pdb

    • saveAsPDB

      void saveAsPDB(MolecularAssembly[] assemblies, File file)
      Saves the current state of an array of MolecularAssembly instances to a PDB file.
      Parameters:
      assemblies - MolecularAssembly array to save
      file - Destination .pdb

    • saveAsPDB

      void saveAsPDB(MolecularAssembly assembly, File file, boolean writeEnd, boolean append)

    • saveAsXYZ

      void saveAsXYZ(MolecularAssembly assembly, File file)
      Saves the current state of a MolecularAssembly to an XYZ file.
      Parameters:
      assembly - MolecularAssembly to save
      file - Destination .xyz

    • saveAsPDBinP1

      void saveAsPDBinP1(MolecularAssembly assembly, File file)
      Saves the symmetry mates of a MolecularAssembly to PDB files.
      Parameters:
      assembly - To save
      file - Destination file

    • time

      double time()
      Logs time elapsed since last call.
      Returns:
      Time.

    • versionFile

      default String versionFile(String filename)
      Versions a file, attempting to find an unused filename in the set filename, and filename_1 to filename_999.
      Parameters:
      filename - To version
      Returns:
      Versioned filename.

    • versionFile

      default File versionFile(File file)
      Versions a file, attempting to find an unused filename in the set filename, and filename_1 to filename_999.
      Parameters:
      file - To version
      Returns:
      Versioned file