ForceGen Files

---===ForceGen===---

ForceGen is a desktop (GUI driven) Java application that takes formatted checkpoint data from Gaussian and derives atomic force constants and equilibrium values for bond stretch and bond angle. The output is compatible with the Gromacs implementation of the Amber ForceField family. 

ZIP Contents:
---------------------
This zip is self contained. The only files required beyond the contents of this zip are downloadable from the links given in the "Prerequisites" below. The contents of this zip are:

README
angletest.dat
biphenyl.fchk
biphenyl.out
LICENSE


Prerequisites:
----------------------
As ForceGen was written in Java, there is no need to configure, install (make) or test this distribution. However, your machine must have the following Java distribution and Java library files:

1) The latest Java Runtime Environment (JRE). 
This distribution of ForceGen was compiled with java version "1.8.0_60".
If you are not sure what version of Java you have, for Mac/Linux, switch to a console window and type:

java -version

For Windows please consult an IT admin if you are unsure of how to find your Java version.

2) Additional Java libraries.
ForceGen makes use of two common mathematical library packages:
-Jave Matrix Package: Jama-1.0.3  http://math.nist.gov/javanumerics/jama/#Package
-Commons Math: The Apache Commons Mathematics Library: Commons-Maths3-3.5  http://commons.apache.org/proper/commons-math/

Deployment:
----------------------
1) Copy the ForceConstants.jar file to a folder of your choice. 
2) That’s it!

Execution
-----------------------
ForceGen can be executed over your desktop through mouse activation as with any other executable link (double click, right-click -> "Run", etc), over via a Mac/Linux terminal. A terminal execution requires the line:

java -jar ForceConstants.jar

The GUI will launch. If you running over a secure shell, this may take a few second. 
It is prudent to first execute "java -version" just to ensure that your distribution of Java can be launched over the command line. If you are executing ForceGen over a remote terminal e.g., ssh onto a university cluster, ensure you have requested X11 support e.g., ssh -X username@myuniversity.cluster.ac.uk. 

Instructions of use:
-----------------------
Single force constant parameterisation use.

        1.Load a Gaussian .log/.out text file and a formatted Gaussian checkpoint file by selecting the respective file selection buttons towards the top of the application window.
        2. To change between bond stretch and bond angle force constant derivation use the combobox to the left of the applicaiton window.
        3. Enter the atom IDs as denoted in the Gaussian log file. A displaced atom during bond stretch force constant derivation is the atom which is displaced relative to a second atom which could be considered as fixed.
        The bond angle force constant derivation requires three atom IDs, two displaced atoms A and C (a combination of vibrations: scissoring and rocking), and a fixed atom B, to make the angle A-B-C. 
        4. Derive the force constant by clicking the 'Calculate' button.
        
The derived force constant will be reported in units compatible with the Amber MD code and the Gromacs MD code. The raw Hessian followed by the mass weighted Hessian are also visible in the output screen.
        
Multiple force constant parameterisation use through atom connectivity file description.

An atom connectivity file provides an automated process of deriving multiple stretch or angle force constants at anyone time. It will also derive bond lengths and bond angles for Gromacs and bond lengths for Amber. These parameters are written to a single FC.dat file which can be used to populate frcmod.known and ffbonded.itp for Amber and Gromacs, respectively.
        1. Prepare an ASCII text file (best through Vi or emacs to avoid hidden metadata). For the derivation of bond stretch force constants the first line should read Stretch, otherwise Angle.
        2.Each additional line should only contain atom connectivity, avoid blank lines. For the software to retrieve the correct atom from the Gaussian files us the atom IDs to denote connectivity. For example over two individual files:

        stretchfile.dat
        Stretch
        1 2
        2 3
        3 4
        10 11

        anglefile.dat
        Angle
        1 2 3
        2 3 4
        3 4 5
        
        
        3. Atom types if provided are used to match the Gromacs and Amber library file format. This will result in equlibrium bond stretch and bond angle calculation. Simply add the atom types in your input <i>file.dat</i> file after each row of respective atom IDs. For example:
        stretchfile.dat
        Stretch
        1 2 N CA
        2 3 CA C
        3 4 CA O
        Note: All atom types must be supplied, or no types at all. If no types are supplied, the regular output of atom IDs and force constants are saved. Providing atom types will result in the following format for bond stretch:
        GROMACS - atom types internal to Gromacs (supplied by user)
        i       j       func    len_eq(nm)      FC (kJ/mol/nm^2)
        AMBER - atom types internal to Amber (supplied by user)
        BOND    FC(kcal/mol/rad^2)      len_eq(Angstrom)

        And for bond angle for constants:
        AMBER - atom types internal to Amber (supplied by user)
        ANGLE   FC(kcal/mol/rad^2)      deg_eq(degree)
        GROMACS - atom types internal to Gromacs (supplied by user)
        i       j       k       func    deg_eq(degree)  FC (kJ/mol/rad^2)
        
        4. To derive the force constant from the input file, select the Atom Data button. Load the formatted .dat file.
        5. The force constant output will be stored in a FC.dat file in the same directory as the atom connectivity input file. <b>Warning</b> This program currently over writes the FC.dat file.