Sample Images of ffTK GUI
ffTK GUI

Overview

The Force Field Toolkit is comprised of a set of tools that aid users in the development of CHARMM-compatible forcefield parameters, including charges, bonds, angles, and dihedrals. These tools are accessed through the provided GUI, which greatly simplifies the setup and analysis of the underlying calculations. Currently, the toolkit assumes that all QM target data is generated using Gaussian; however, we plan to expand functionality to include alternatives.

To get the most out of the ffTK, a reasonable understanding of the CHARMM and CGenFF force fields is required. For additional information on these topics and the underlying principles of parameterization, users are urged to also visit Alex MacKerell's website for CHARMM FF Parameters and the CHARMM user forums, specifically the parameterization section.

The ffTK plugin relies on a number of other VMD plugins, described in more detail here: Multiplot NAMD Energy Optimization QM Tool Topo Tools

BuildPar

BuildPar is a collection of three tools for identifying missing parameters, building an initial parameter file, and updating the new parameter file based on ffTK output.

Opt. Geometry

Description:
The Opt. Geometry tab is designed to simplify the process of obtaining a QM-optimized structure for a given molecule.
Usage:
The top section of the tool serves to write the Gaussian input file (GAU), while the bottom section allows the user to visualize the optimization steps and write out a final structure to a PDB file.
Input:
  • Input PDB File: The location and filename of PDB file containing the initial coordinates.
  • Output GAU File: A location and filename for the generated Gaussian input file.
  • Gaussian Settings: The default Gaussian settings are for a geometry optimization at the MP2/6-31G* level of theory for a neutral molecule, and should be suitable for most cases.
  • Original PDB File: The location and filename of the PDB file used as the Input PDB File above.
  • Gaussian LOG File: The location and filename of the LOG file generated from the Gaussian calculation.
  • Output PDB File: A location and filename for the output PDB file containing the QM-optimized atomic coordinates (geometry).
Output:
  • A Gaussian input file (GAU) for running the Gaussian calculation.
  • A PDB file containing the QM-optimized atomic coordinates (geometry).

Water Int.

Description:
The Water Int. tab is designed to aid the user in generating the QM water interaction target data used in charge optimization.
Usage:
The user provides the requested input information regarding the molecule, followed by loading the molecule into VMD (Load PSF/PDB button). The Hydrogen Bonding Atoms box provides several tools for assigning donor and acceptor indices. These tools include, atom labeling, colored spheres for each listed index, and a routine that autofills the donor/acceptor lists based on a relatively simple algorithm. Default settings for the Gaussian calculation are provided in the Gaussian Settings box. The Write Gaussian Input Files button generates a Gaussian input file (GAU) that optimizes the interaction of a water molecule with a specific atom, provided in the donor/acceptor lists. The resulting GAU file(s) should be checked visually by loading them into VMD via the Load GAU Files button. After the Gaussian calculations have completed, the user can visualize the optimization steps by loading the LOG file(s) generated from each Gaussian calculation via the Load LOG Files button.
Input:
  • PSF File: The location and filename of the PSF file describing the molecule.
  • PDB File: The location and filename of the PDB file containing the QM-optimized geometry.
  • Output Path: The location where GAU files will be written.
  • Basename: A short abbreviation used for naming GAU files; generally the residue name.
  • Donor Indices: The index for each atom that will positively interact with the oxygen atom of a water molecule.
  • Acceptor Indices: The index for each atom that will positively interact with the hydrogen atom of a water molecule.
  • Gaussian Settings: The default Gaussian settings optimize the distance and orientation of the water molecule with respect to a given atom in the molecule at the RHF/6-31G* level of theory. These settings should be suitable for most cases.
Output:
A Gaussian input file (GAU) for each index provided in the donors/acceptors lists.

Opt.Charges

Description:
The Opt. Charges tab is used to setup and run a calculation that optimizes atomic partial charges to reproduce water interaction QM target data using MM calculations. The optimization requires a number of settings, which are broken down into sections that will be described separately.
Usage:
Appropriate data are assigned for Input, Charge Constraints, and QM Target Data sections. The optimization is launched by the Run Optimization button, whereby the status label will update periodically during the calculation. Upon completion, the status returns to IDLE and the optimized charge data is loaded into the Results section. A new PSF file containing the optimized charges can be written by specifying a location and filename in the Update PSF with new charges box, and clicking the Write button. Note that writing a new PSF requires that the PSF and PDB entries are set in the Input section. The results from previous charge optimizations can be reloaded by specifying the ffTK output log file into Load output file from a previous optimization and selecting the Load button.
Input/Settings:
  • ► Input
    • PSF File: The location and filename of the PSF file describing the molecule.
    • PDB File: The location and filename of the PDB file containing the QM-optimized geometry.
    • Residue Name: The VMD resname abbreviation for the molecule.
    • Parameter Files: Any parameter files that are required for simulation of the molecule. This includes associated parameter files, as well as the initial parameter file that is under development.
    • NAMD binary: The location of NAMD binary file, or simply the filename if the location is included in the PATH.
    • Output LOG: A location and filename for ffTK output log file (LOG).
  • ► Charge Constraints
    • Charge Group: A list of atom names that will be forced to have the same charge.
    • Initial Charge: An initial charge assigned to the charge group. Cannot be zero.
    • Low Bound: The lowest charge that can be assigned to the charge group.
    • High Bound: The highest charge that can be assigned to the charge group.
    • Charge Sum: The total sum of all charges to be optimized. This setting ensures that the molecule has an overall integer charge, usually zero.

    • Charge groups should only contain atoms for which charges will be optimized. Each group can be added manually, or guessed using an algorithm that assigns charge groups based on chemical equivalency if the PSF/PDB has been loaded into VMD as the TOP molecule (see Input section). The Input section also has a tool to show a variety of labels for each atom to aid in assigning charge groups. The Calculate from TOP button calculates the charge sum using charges found in the PSF, and assumes a neutral molecule. Either of these assumptions can be incorrect, and the user is encouraged to carefully check this number.
  • ► QM Target Data
    • Cmpd LOG: The location and filename of the Gaussian log file containing the single point energy calculated for the molecule at the same level as the water interaction (e.g., RHF/6-31G*).
    • Water LOG: The location and filename of the Gaussian log file containing the single point energy calculated for a TIP3 water molecule calculated at the same level as the water interaction (e.g., RHF/6-31G*).
    • LOG File: Log file for each QM-calculated water interaction.
    • Atom Name: The atom name for the atom specified in the water interaction calculation.
    • Weight: A weighting factor for the associated water interaction data.

      The geometry optimization is typically calculated at MP2/6-31G*, and therefore, a separate single point energy calculation of the optimized geometry at RHF/6-31G* is required for the Cmpd LOG. The Water Interaction Energy Data are loaded via the add button. If the water interaction energy data were generated using the Water Int. tab, then the Atom Name will be automatically parsed from the filename and set accordingly. One exception to this is for water interaction files probing a carbonyl, which will need to be modified to give the appropriate atom name due to a difference in the default GAU file naming scheme.
  • ► Advanced Settings
    • Start, End, Delta: Control how the water molecule is moved with respect to the specified atom during the MM calculation.
    • Offset: Adjustment applied to distance of the water molecule at the QM energy minimum to account for differences between gas-phase and bulk-phase calculations.
    • Scale: Scaling factor applied to the QM minimum energy to account for the difference between gas-phase and bulk-phase calculations.
    • Tolerance: Tolerance for optimization function
    • Dist. Weight: Weighting factor of QM Distance relative to QM energy. Default is 1.0. Values < 1.0 weight energy more heavily and are reasonable, if not desired.
    • Mode: Defines how the optimizer runs; downhill and simulated annealing are supported (see Optimization for details).
    • Override ReChargeFromPSF: If checked, replaces charges from PSF with those provided for the specified atom name during the optimization. Note, that Charge Sum will likely need to be calculated manually if this is checked.
    • Write debugging log: If checked, output also includes a .debug.log file that contains detailed information about the setup and calculation.
    • Build Run Script: If checked, instead of running the optimization immediately, it generates a script with all of the commands necessary to setup and run the optimization. Useful for running the optimization with VMD in text mode. Note that input files are assigned with absolute paths, and may need to be adjusted if the script is launched from a machine with a different filesystem.
  • ► Results
    • The results provide the optimized charge calculated for each charge group. The Charge Total should match the Charge Sum set in Charge Constraints; however, rounding errors can occur. In such cases, select a charge group entry and adjust the charge as necessary. Updating the PSF and loading other outputs are discussed in Usage above.
Output:
A ffTK log file for use in updating charges via the Update PSF with new charges in the Results section.

Calc. Bonded

Description:
The Calc. Bonded tab is used to setup the Gaussian calculation of the hessian, and transform the resulting matrix to obtain the bonded parameters (bonds, angles).
Usage:
The user provides the location and filename of the Gaussian checkpoint (CHK) file generated during the geometry optimization (Opt. Geometry), and a filename for a Gaussian input file to calculate the hessian, which is written using the Write Gaussian Input File button. Upon completion of the Gaussian calculation, the user provides additional input information, and a filename for an ffTK output file. The Calculate Bonded Parameters button uses the input information to generate and ffTK file for use in BuildPar to update the bonded parameters in the developing parameter file.
Input:
  • Gaussian Settings: Default settings are provided for calculation of the hessian at MP2/6-31G* level of theory.
  • Geometry Optimization CHK File: The location and filename of the Gaussian checkpoint file generated during the geometry optimization. Note: Calc. Bonded makes a copy of this file, preventing an overwrite of the original by Gaussian.
  • Output GAU File: A location and filename for the generated Gaussian input file.
  • PSF File: The location and filename for the PSF file describing the molecule.
  • PDB File: The location and filename for the PDB file describing the geometry optimized structure.
  • Template PAR File: The location and filename for the developing parameter file.
  • Gaussian LOG File: The location and filename for the log file generated by Gaussian during the hessian calculation.
  • Output File: A location and filename for the ffTK output file.
Output:
  • A Gaussian input file for running the hessian calculation.
  • A Gaussian checkpoint file used during the hessian calculation.
  • A ffTK output file for use in BuildPar to update the bond and angle parameters.

Scan Torsions

Description:
The Scan Torsions tab is designed to aid the user in generating the QM target data used to optimize dihedral parameters from torsion scans.
Usage:
The user provides required input/output information. Loading the PSF/PDB allows the user access to several tools for selecting dihedral angles to be scanned. The preferred method for adding entries to the Dihedrals to Scan box is via the Read from PAR button. This button uses a dialog to identify the parameter file under development, from which dihedrals missing parameters are read, and non-redundant torsions are added to the box, and the Equilibrium Value is set to the measured dihedral angle. Each dihedral can be visualized in VMD by selecting the entry. Dihedrals can also be added manually via the add button. The Generate Dihedral Scan Input Files button generates two Gaussian input files per scan, one in the positive direction and one in the negative direction.
Input:
  • PSF File: The location and filename for the PSF file describing the the molecule.
  • PDB File: The location and filename for the PDB file describing the geometry optimized structure.
  • Output Path: The location where Gaussian input files are written.
  • Basename: A short abbreviation used for naming GAU files; generally the residue name.
  • Dihedral Atoms: Indices describing torsion to scan.
  • Equilibrium Value: Value from which to start the scan (center value; degrees).
  • +/-: Range to scan from Equilibrium Value in either direction (degrees).
  • Step Size: Distance between scan steps (degrees).
  • Gaussian Settings: The default Gaussian settings perform a relaxed potential energy scan at the MP2/6-31G* level of theory. These settings should be suitable for most cases.
Output:
Two Gaussian input files for each entry of the Dihedrals to Scan box.

Opt. Torsions

Description:
The Opt. Torsions tab provides the tools to setup and run calculations that optimize dihedral angle parameters to reproduce QM relaxed potential energy scans. The optimization requires a number of settings, which are broken down into sections that will be described separately.
Usage:
Appropriate data are assigned for Input, QM Target Data, and Dihedral Parameter Settings sections. The initial optimization is launched by the Run Optimization button, whereby the status label will update periodically during the calculation. Upon completion, the status returns to IDLE and optimization data is loaded into the Visualize Results section. Here, the data can be plotted against the QM target data (QME) and the initial MM data that excludes energy contributions from the dihedrals being fit (MMEi). The initial optimization usually requires refinement through the use of the Refine section. Initial optimization is copied to the Refine section by selecting the entry in the Visualize Results box and clicking the Set As Refit Input button. Within the Refine box, various attributes of the optimization can be changed, including dihedral parameter descriptions and optimization settings. The Run Refitting/Refinement button launches the refinement protocol, which is often substantially faster than the original optimization routine. This is because the initial optimization protocol requires a restrained minimization performed on each target datapoint prior to optimization. The relevant dihedral information is stored in dihAll (see Reference Data in Visualize Results section), greatly speeding subsequent optimizations/refinements. The user can iteratively adjust dihedral and optimization settings until arriving at an appropriate root-mean-square error (RMSE).
Input/Settings:
  • ► Input
    • PSF File: The location and filename of the PSF file describing the molecule.
    • PDB File: The location and filename of the PDB file containing the QM-optimized geometry.
    • Parameter Files: Any parameter files that are required for simulation of the molecule. This includes associated parameter files, as well as the initial parameter file that is under development.
    • NAMD binary: The location of the NAMD executable, or simply its name if the location is included in the PATH.
    • Output LOG: A location and filename for ffTK output log file (LOG).
  • ► QM Target Data
    • Location and filenames for Gaussian log files of relaxed potential energy scans.
  • ► Dihedral Parameter Settings
    • The preferred method for setting the dihedral parameters is via the Read from PAR button, which reads in the missing dihedral parameters from the parameter file under development. The user should modify the periodicity based on knowledge of the type definitions and the bonding geometries and hybridization states of the atoms involved (e.g., for central atoms with sp2 hybridization, n=2). The optimization supports multiplicities, although the user should exercise caution. ffTK only supports phase shift values of 0 and 180 degrees.
  • ► Advanced Settings
    • Kmax: The maximum value allowed for a force constant.
    • Energy Cutoff: The QM energy threshold for inclusion in the optimization. Molecule conformations above this threshold will have their weighting factors set to zero.
    • Tolerance: Tolerance for optimization function
    • Mode: Defines how the optimizer runs; downhill and simulated annealing are supported (see Optimization for details). .
    • Write debugging log: If checked, output also includes a .debug.log file that contains detailed information about the setup and calculation.
    • Build Run Script: If checked, instead of running the optimization immediately, it generates a script with all of the commands necessary to setup and run the optimization. Useful for running the optimization with VMD in text mode. Note that input files are assigned with absolute paths, and may need to be adjusted if the script is launched from a machine with a different filesystem.
    • Output Freq.: The frequency (iteration number) with which data is written to the ffTK output file, and status label updates.
  • ► Visualize Results
    • Data Set/RMSE/Plot Color: Attributes for optimization data sets.
    • Set Data Color: Change the plot color for selected data sets.
    • Plot Selected: Opens a multiplot window and plots selected data sets.
    • Include QME/Include MMEi: If checked, includes the QME target data, and the MMEi data in the plot. Default is on.
    • Import From LOG: Loads optimization data (initial or refined).
    • Write Selected to LOG: Saves data necessary for reloading (via Import from LOG) and optimized parameters for use in BuildPar to update the dihedral parameters for each selected dataset.
    • Set As Refit Input: Copies the final parameter data from the selected dataset into the Refine section.
  • ► Refine
    • The refinement parameters hold equivalent functions to those described in previous sections, but are only applied to the refitting/refinement optimizations.
Output:
A ffTK log file for use in updating dihedral parameters in the parameter file under development using BuildPar.

GUI Event Log

Description:
Logs the most recent 100 GUI events. The primary functions is to inform the user of GUI actions that lack visual feedback (e.g., update buttons, write buttons).
Usage:
Click on GUI Event Log label to turn on/off.

Citation

Mayne, C.G.; Tajkhorshid, E.; and Gumbart, J. (2012) Manuscript in preparation.

Authors

Christopher G. Mayne and James C. Gumbart