ForceFieldMMFF
Date: 2019-10-22

org.jmol.minimize.forcefield

## Class ForceFieldMMFF

- java.lang.Object
- - org.jmol.minimize.forcefield.ForceField
  - - org.jmol.minimize.forcefield.ForceFieldMMFF

-     public class ForceFieldMMFF
      extends ForceField

  MMFF94 implementation 5/14/2012 - fully validated for atom types and charges - reasonably well validated for energies (see below) - TODO: add UFF for preliminary/backup calculation
  Author:
    Bob Hanson hansonr@stolaf.edu Java implementation by Bob Hanson 5/2012 based loosely on chemKit code by Kyle Lutz and OpenBabel code by Tim Vandermeersch but primarily from what is described in T. A. Halgren; "Merck Molecular Force Field. V. Extension of MMFF94 Using Experimental Data, Additional Computational Data, and Empirical Rules", J. Comp. Chem. 5 & 6 616-641 (1996). Parameter files are clipped from the original Wiley FTP site supplemental material: ftp://ftp.wiley.com/public/journals/jcc/suppmat/17/490/MMFF-I_AppendixB.ascii Original work, as listed at http://towhee.sourceforge.net/forcefields/mmff94.html: T. A. Halgren; "Merck Molecular Force Field. I. Basis, Form, Scope, Parameterization, and Performance of MMFF94", J. Comp. Chem. 5 & 6 490-519 (1996). T. A. Halgren; "Merck Molecular Force Field. II. MMFF94 van der Waals and Electrostatic Parameters for Intermolecular Interactions", J. Comp. Chem. 5 & 6 520-552 (1996). T. A. Halgren; "Merck Molecular Force Field. III. Molecular Geometries and Vibrational Frequencies for MMFF94", J. Comp. Chem. 5 & 6 553-586 (1996). T. A. Halgren; R. B. Nachbar; "Merck Molecular Force Field. IV. Conformational Energies and Geometries for MMFF94", J. Comp. Chem. 5 & 6 587-615 (1996). T. A. Halgren; "Merck Molecular Force Field. V. Extension of MMFF94 Using Experimental Data, Additional Computational Data, and Empirical Rules", J. Comp. Chem. 5 & 6 616-641 (1996). T. A. Halgren; "MMFF VII. Characterization of MMFF94, MMFF94s, and Other Widely Available Force Fields for Conformational Energies and for Intermolecular-Interaction Energies and Geometries", J. Comp. Chem. 7 730-748 (1999). Validation carried out using MMFF94_opti.log and MMFF94_dative.mol2 (or MMFF94_hypervalent.mol2) including 761 models using org/jmol/minimize/forcefield/mmff/validate/checkmm.spt (checkAllEnergies) All typical compounds validate. The following 7 structures do not validate to within 0.1 kcal/mol total energy; version=12.3.26_dev # code: adding empirical rules to MMFF94 calculation # # checkmm.spt;checkAllEnergies # # checking calculated energies for 761 models # 1 COMKAQ E= -7.3250003 Eref= -7.6177 diff= 0.2926998 # 2 DUVHUX10 E= 64.759995 Eref= 64.082855 diff= 0.6771393 # 3 FORJIF E= 35.978 Eref= 35.833878 diff= 0.14412308 # 4 JADLIJ E= 25.104 Eref= 24.7038 diff= 0.4001999 # 5 PHOSLA10 E= 111.232994 Eref= 112.07078 diff= 0.8377838 # 6 PHOSLB10 E= -93.479004 Eref= -92.64081 diff= 0.8381958 # # for 761 atoms, 6 have energy differences outside the range -0.1 to 0.1 # with a standard deviation of 0.05309403 # # a comment about empirical bond parameter calculation: # # // Well, guess what? As far as I can tell, in Eqn 18 on page 625, # // the reduction term and delta are zero. # # // -- at least in the program run that is at the validation site: # // OPTIMOL: Molecular and Macromolecular Optimization Package 17-Nov-98 16:01:23 # // SGI double-precision version ... Updated 5/6/98 # // # // This calculation is run only for the following three structures. In each case the # // reported validation values and values from Jmol 12.3.26_dev are shown. Clearly # // the r0 calculated and final energies are very good. subtracting off 0.008 from # // r0 would certainly not give the reported values. Something is odd there. # // # // bond red* r0(here/valid) kb(here/valid) Etotal(here/valid) # // --------------------------------------------------------------------------------------- # // OHWM1 H1-O1 0.03 0.978/0.978 7.510/7.51 -21.727/-21.72690 # // ERULE_03 Si1-P1 0.0 2.223/2.224 1.614/1.609 -2.983/ -2.93518 # // ERULE_06 N1-F1 0.0 1.381/1.379 5.372/5.438 1.582/ 1.58172 # // # // *reduction and delta terms not used in Jmol's calculation # # COMKAQ -- BATCHMIN ignores 1 of 5-membered ring torsions for a 1-oxo-2-oxa-bicyclo[3.2.0]heptane -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate DUVHUX10 -- BATCHMIN ignores 5-membered ring issue for S-S-containing ring -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate FORJIF -- BATCHMIN misses four standard 5-membered C-C ring bonds -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate JADLIJ -- BATCHMIN ignores 5-membered ring for S (note, however, this is not the case in BODKOU) -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate PHOSLA10 -- BATCHMIN ignores all 5-membered ring torsions in ring with P -- (note, however, this is not the case in CUVGAB) -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate PHOSLB10 -- BATCHMIN ignores all 5-membered ring torsions in ring with P -- (note, however, this is not the case in CUVGAB) -- MMFF94_bmin.log: WARNING - Conformational Energies May Not Be Accurate OHMW1 -- H2O complexed with hydroxide OH(-) -- I don't understand (a) why the OH(-) bond has mltb=1, and even with that I am not getting the correct ro/kb for that bond from empirical rules. Still working on that....

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static int` | `A4_BNDK`
    `private static int` | `A4_CHRG`
    `private static int` | `A4_SB`
    `private static int` | `A4_SBDEF`
    `private static int` | `A4_VDW`
    `private static javajs.util.Lst<AtomType>` | `atomTypes`
    `private static int[]` | `equivalentTypes`
    `private static java.util.Map<java.lang.Object,java.lang.Object>` | `ffParams`
    `private static int` | `KEY_BNDK`
    `private static int` | `KEY_OOP`
    `private static int` | `KEY_PBCI`
    `private static int` | `KEY_SBDEF`
    `private static int` | `KEY_VDW`
    `private java.lang.String` | `line`
    `private static java.lang.String` | `names`
    `private int[]` | `rawAtomTypes`
    `private int[]` | `rawBondTypes`
    `private float[]` | `rawMMFF94Charges`
    `private static int[]` | `sbMap`
    `private static int` | `TYPE_ANGLE`
    `private static int` | `TYPE_BNDK`
    `private static int` | `TYPE_BOND`
    `private static int` | `TYPE_CHRG`
    `private static int` | `TYPE_OOP`
    `private static int` | `TYPE_PBCI`
    `private static int` | `TYPE_SB`
    `private static int` | `TYPE_SBDEF`
    `private static int` | `TYPE_TORSION`
    `private static int` | `TYPE_VDW`
    `private int[]` | `typeData`
    `private static int[]` | `types`
    `private javajs.util.Lst<javajs.util.BS>[]` | `vRings`

    - ### Fields inherited from class org.jmol.minimize.forcefield.ForceField

      `ABI_IJ, ABI_JK, bsFixed, calc, currentStep, EANGLE, EBOND, EELECTROSTATIC, ENERGY, EOOP, ESTRBND, ETORSION, EVDW, minAngles, minAtomCount, minAtoms, minBondCount, minBonds, minimizer, minPositions, minTorsions, name, R3, R4, R5, Raromatic, TBI_AB, TBI_BC, TBI_CD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ForceFieldMMFF(Minimizer m)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private java.lang.Integer` | `applyEmpiricalRules(MinObject o, double[] ddata, int ktype)`
    `static float[]` | `calculatePartialCharges(Bond[] bonds, int[] bTypes, Atom[] atoms, int[] aTypes, javajs.util.BS bsAtoms, boolean doRound)` assign partial charges ala MMFF94
    `private boolean` | `checkRings(javajs.util.Lst<javajs.util.BS> v, int[] minlist, int n)`
    `void` | `clear()`
    `private double` | `dval(int i, int j)`
    `private int` | `fixOrder(int[] a, int i, int j)`
    `private static boolean` | `fixTypeOrder(int[] a, int i, int j)`
    `private boolean` | `fixTypes()`
    `private float` | `fval(int i, int j)`
    `java.lang.String[]` | `getAtomTypeDescriptions()`
    `static java.lang.String[]` | `getAtomTypeDescs(int[] types)`
    `private void` | `getAtomTypes()`
    `private int` | `getBondType(Bond bond, AtomType at1, AtomType at2, int index1, int index2)`
    `private static double` | `getCovalentRadius(int elemno)`
    `private static double` | `getCParam(int elemno)`
    `private static int` | `getEquivalentType(int type, int level)` equivalent types for OOP and torsions
    `private java.lang.Integer` | `getKey(java.lang.Object obj, int type, int ktype)`
    `(package private) double` | `getOutOfPlaneParameter(int[] data)`
    `private void` | `getParameters()`
    `float[]` | `getPartialCharges()`
    `private static double` | `getR0(MinBond b)`
    `private int` | `getRowFor(int i)`
    `private static double` | `getRuleBondLength(MinAtom a, MinAtom b, int boAB, boolean isAromatic)`
    `private java.lang.Integer` | `getTorsionKey(int type, int i, int j)`
    `private static double` | `getUParam(int elemno)`
    `private static double` | `getVParam(int elemno)`
    `private static double` | `getZParam(int elemno)`
    `private boolean` | `isAromaticBond(int a1, int a2)`
    `private static boolean` | `isBondType1(AtomType at1, AtomType at2)`
    `private int` | `ival(int i, int j)`
    `private void` | `readParams(java.io.BufferedReader br, int dataType, java.util.Map<java.lang.Object,java.lang.Object> data)`
    `private int` | `setAngleType(MinAngle angle)`
    `boolean` | `setArrays(Atom[] atoms, javajs.util.BS bsAtoms, Bond[] bonds, int rawBondCount, boolean doRound, boolean allowUnknowns)`
    `private static int[]` | `setAtomTypes(Atom[] atoms, javajs.util.BS bsAtoms, SmilesMatcherInterface smartsMatcher, javajs.util.Lst<javajs.util.BS>[] vRings, boolean allowUnknowns)` The file MMFF94-smarts.txt is derived from MMFF94-smarts.xlsx.
    `private int[]` | `setBondTypes(Bond[] bonds, int bondCount, javajs.util.BS bsAtoms)`
    `private static void` | `setFlags(AtomType at)`
    `boolean` | `setModel(javajs.util.BS bsElements, int elemnoMax)`
    `private int` | `setTorsionType(MinTorsion t)`
    `private static void` | `sortOop(int[] typeData)`
    `private static void` | `swap(int[] a, int i, int j)`
    `private int` | `typeOf(int iAtom)`

    - ### Methods inherited from class org.jmol.minimize.forcefield.ForceField

      `detectExplosion, energyAngle, energyBond, energyES, energyFull, energyOOP, energyStretchBend, energyTorsion, energyVDW, getAtomList, getBufferedReader, getCurrentStep, getEnergy, getEnergyDiff, getLogData, getNormalizedDE, log, setConstraints, setModelFields, steepestDescentInitialize, steepestDescentTakeNSteps, toUserUnits`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### A4_VDW

          private static final int A4_VDW

      See Also:
        Constant Field Values

    - #### A4_BNDK

          private static final int A4_BNDK

      See Also:
        Constant Field Values

    - #### A4_CHRG

          private static final int A4_CHRG

      See Also:
        Constant Field Values

    - #### A4_SB

          private static final int A4_SB

      See Also:
        Constant Field Values

    - #### A4_SBDEF

          private static final int A4_SBDEF

      See Also:
        Constant Field Values

    - #### KEY_SBDEF

          private static final int KEY_SBDEF

      See Also:
        Constant Field Values

    - #### KEY_PBCI

          private static final int KEY_PBCI

      See Also:
        Constant Field Values

    - #### KEY_VDW

          private static final int KEY_VDW

      See Also:
        Constant Field Values

    - #### KEY_BNDK

          private static final int KEY_BNDK

      See Also:
        Constant Field Values

    - #### KEY_OOP

          private static final int KEY_OOP

      See Also:
        Constant Field Values

    - #### TYPE_PBCI

          private static final int TYPE_PBCI

      See Also:
        Constant Field Values

    - #### TYPE_VDW

          private static final int TYPE_VDW

      See Also:
        Constant Field Values

    - #### TYPE_BNDK

          private static final int TYPE_BNDK

      See Also:
        Constant Field Values

    - #### TYPE_CHRG

          private static final int TYPE_CHRG

      See Also:
        Constant Field Values

    - #### TYPE_BOND

          private static final int TYPE_BOND

      See Also:
        Constant Field Values

    - #### TYPE_ANGLE

          private static final int TYPE_ANGLE

      See Also:
        Constant Field Values

    - #### TYPE_SB

          private static final int TYPE_SB

      See Also:
        Constant Field Values

    - #### TYPE_SBDEF

          private static final int TYPE_SBDEF

      See Also:
        Constant Field Values

    - #### TYPE_TORSION

          private static final int TYPE_TORSION

      See Also:
        Constant Field Values

    - #### TYPE_OOP

          private static final int TYPE_OOP

      See Also:
        Constant Field Values

    - #### atomTypes

          private static javajs.util.Lst<AtomType> atomTypes

    - #### ffParams

          private static java.util.Map<java.lang.Object,java.lang.Object> ffParams

    - #### rawAtomTypes

          private int[] rawAtomTypes

    - #### rawBondTypes

          private int[] rawBondTypes

    - #### rawMMFF94Charges

          private float[] rawMMFF94Charges

    - #### vRings

          private javajs.util.Lst<javajs.util.BS>[] vRings

    - #### names

          private static final java.lang.String names

      See Also:
        Constant Field Values

    - #### types

          private static final int[] types

    - #### line

          private java.lang.String line

    - #### sbMap

          private static final int[] sbMap

    - #### typeData

          private int[] typeData

    - #### equivalentTypes

          private static final int[] equivalentTypes

  - ### Constructor Detail

    - #### ForceFieldMMFF

          public ForceFieldMMFF(Minimizer m)
                         throws JmolAsyncException

      Throws:
        `JmolAsyncException`

  - ### Method Detail

    - #### getAtomTypeDescriptions

          public java.lang.String[] getAtomTypeDescriptions()

    - #### getPartialCharges

          public float[] getPartialCharges()

    - #### clear

          public void clear()

      Specified by:
        `clear` in class `ForceField`

    - #### setModel

          public boolean setModel(javajs.util.BS bsElements,
                                  int elemnoMax)

      Specified by:
        `setModel` in class `ForceField`

    - #### setArrays

          public boolean setArrays(Atom[] atoms,
                                   javajs.util.BS bsAtoms,
                                   Bond[] bonds,
                                   int rawBondCount,
                                   boolean doRound,
                                   boolean allowUnknowns)

    - #### getParameters

          private void getParameters()
                              throws JmolAsyncException

      Throws:
        `JmolAsyncException`

    - #### readParams

          private void readParams(java.io.BufferedReader br,
                                  int dataType,
                                  java.util.Map<java.lang.Object,java.lang.Object> data)
                           throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### ival

          private int ival(int i,
                           int j)

    - #### fval

          private float fval(int i,
                             int j)

    - #### dval

          private double dval(int i,
                              int j)

    - #### getAtomTypes

          private void getAtomTypes()
                             throws JmolAsyncException

      Throws:
        `JmolAsyncException`

    - #### setFlags

          private static void setFlags(AtomType at)

    - #### calculatePartialCharges

          public static float[] calculatePartialCharges(Bond[] bonds,
                                                        int[] bTypes,
                                                        Atom[] atoms,
                                                        int[] aTypes,
                                                        javajs.util.BS bsAtoms,
                                                        boolean doRound)

      assign partial charges ala MMFF94
      Parameters:
        `bonds` -
        `bTypes` -
        `atoms` -
        `aTypes` -
        `bsAtoms` -
        `doRound` -
      Returns:
        full array of partial charges

    - #### isBondType1

          private static boolean isBondType1(AtomType at1,
                                             AtomType at2)

    - #### getBondType

          private int getBondType(Bond bond,
                                  AtomType at1,
                                  AtomType at2,
                                  int index1,
                                  int index2)

    - #### isAromaticBond

          private boolean isAromaticBond(int a1,
                                         int a2)

    - #### getAtomTypeDescs

          public static java.lang.String[] getAtomTypeDescs(int[] types)

    - #### setAtomTypes

          private static int[] setAtomTypes(Atom[] atoms,
                                            javajs.util.BS bsAtoms,
                                            SmilesMatcherInterface smartsMatcher,
                                            javajs.util.Lst<javajs.util.BS>[] vRings,
                                            boolean allowUnknowns)

      The file MMFF94-smarts.txt is derived from MMFF94-smarts.xlsx. This file contains records for unique atom type/formal charge sharing/H atom type. For example, the MMFF94 type 6 is distributed over eight AtomTypes, each with a different SMARTS match. H atom types are given in the file as properties of other atom types, not as their own individual SMARTS searches. H atom types are determined based on their attached atom's atom type.
      Parameters:
        `atoms` -
        `bsAtoms` -
        `smartsMatcher` -
        `vRings` -
        `allowUnknowns` -
      Returns:
        array of indexes into AtomTypes or, for H, negative of mmType

    - #### setBondTypes

          private int[] setBondTypes(Bond[] bonds,
                                     int bondCount,
                                     javajs.util.BS bsAtoms)

    - #### fixTypes

          private boolean fixTypes()

    - #### setAngleType

          private int setAngleType(MinAngle angle)

    - #### setTorsionType

          private int setTorsionType(MinTorsion t)

    - #### typeOf

          private int typeOf(int iAtom)

    - #### checkRings

          private boolean checkRings(javajs.util.Lst<javajs.util.BS> v,
                                     int[] minlist,
                                     int n)

    - #### getKey

          private java.lang.Integer getKey(java.lang.Object obj,
                                           int type,
                                           int ktype)

    - #### getTorsionKey

          private java.lang.Integer getTorsionKey(int type,
                                                  int i,
                                                  int j)

    - #### applyEmpiricalRules

          private java.lang.Integer applyEmpiricalRules(MinObject o,
                                                        double[] ddata,
                                                        int ktype)

    - #### getR0

          private static double getR0(MinBond b)

    - #### getRowFor

          private int getRowFor(int i)

    - #### getOutOfPlaneParameter

          double getOutOfPlaneParameter(int[] data)

    - #### sortOop

          private static void sortOop(int[] typeData)

    - #### fixTypeOrder

          private static boolean fixTypeOrder(int[] a,
                                              int i,
                                              int j)

      Parameters:
        `a` -
        `i` -
        `j` -
      Returns:
        true if swapped; false if not

    - #### fixOrder

          private int fixOrder(int[] a,
                               int i,
                               int j)

      Parameters:
        `a` -
        `i` -
        `j` -
      Returns:
        1 if in order, 0 if same, -1 if reversed

    - #### swap

          private static void swap(int[] a,
                                   int i,
                                   int j)

    - #### getEquivalentType

          private static int getEquivalentType(int type,
                                               int level)

      equivalent types for OOP and torsions
      Parameters:
        `type` - mmFF94 atom type
        `level` - 0, 1, or 2.
      Returns:
        equivalent type or 0

    - #### getZParam

          private static double getZParam(int elemno)

    - #### getCParam

          private static double getCParam(int elemno)

    - #### getUParam

          private static double getUParam(int elemno)

    - #### getVParam

          private static double getVParam(int elemno)

    - #### getCovalentRadius

          private static double getCovalentRadius(int elemno)

    - #### getRuleBondLength

          private static double getRuleBondLength(MinAtom a,
                                                  MinAtom b,
                                                  int boAB,
                                                  boolean isAromatic)