UFF.hpp

/*
 * Copyright (c) 2020 The University of Notre Dame. All Rights Reserved.
 *
 * The University of Notre Dame grants you ("Licensee") a
 * non-exclusive, royalty free, license to use, modify and
 * redistribute this software in source and binary code form, provided
 * that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the
 *    distribution.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. All express or implied conditions, representations and
 * warranties, including any implied warranty of merchantability,
 * fitness for a particular purpose or non-infringement, are hereby
 * excluded.  The University of Notre Dame and its licensors shall not
 * be liable for any damages suffered by licensee as a result of
 * using, modifying or distributing the software or its
 * derivatives. In no event will the University of Notre Dame or its
 * licensors be liable for any lost revenue, profit or data, or for
 * direct, indirect, special, consequential, incidental or punitive
 * damages, however caused and regardless of the theory of liability,
 * arising out of the use of or inability to use software, even if the
 * University of Notre Dame has been advised of the possibility of
 * such damages.
 *
 * SUPPORT OPEN SCIENCE!  If you use OpenMD or its source code in your
 * research, please cite the appropriate papers when you publish your
 * work.  Good starting points are:
 *
 * [1] Meineke, et al., J. Comp. Chem. 26, 252-271 (2005).
 * [2] Fennell & Gezelter, J. Chem. Phys. 124, 234104 (2006).
 * [3] Sun, Lin & Gezelter, J. Chem. Phys. 128, 234107 (2008).
 * [4] Vardeman, Stocker & Gezelter, J. Chem. Theory Comput. 7, 834 (2011).
 * [5] Kuang & Gezelter, Mol. Phys., 110, 691-701 (2012).
 * [6] Lamichhane, Gezelter & Newman, J. Chem. Phys. 141, 134109 (2014).
 * [7] Lamichhane, Newman & Gezelter, J. Chem. Phys. 141, 134110 (2014).
 * [8] Bhattarai, Newman & Gezelter, Phys. Rev. B 99, 094106 (2019).
 */
 
// This implementation was created based on open code and reference websites:
// http://towhee.sourceforge.net/forcefields/uff.html
// http://rdkit.org/
// http://openbabel.org
// http://franklin.chm.colostate.edu/mmac/uff.html
// (for the last, use the Wayback Machine: http://www.archive.org/
 
// As well, the main UFF paper:
// Rappe, A. K., et. al.; J. Am. Chem. Soc. (1992) 114(25) p. 10024-10035.
 
#ifndef FORCEFIELDS_UFF_HPP
#define FORCEFIELDS_UFF_HPP
 
#include "types/AtomType.hpp"
 
namespace OpenMD {
  namespace UFF {
    namespace Params {
      const RealType lambda = 0.1332;  //!< scaling factor for rBO correction
      const RealType G = 332.06;       //!< bond force constant prefactor
      const RealType amideBondOrder =
        1.41;  //!< special case bond order for amide C-N bonds.
    };         // namespace Params
    
 
    //! calculates and returns the UFF rest length for a bond
    /*!
      \param bondOrder the order of the bond (as a RealType)
      \param at1  pointer to the AtomType for atom 1
      \param at2  pointer to the AtomType for atom 2
      \return the rest length
    */
    RealType calcBondRestLength(RealType bondOrder,
                                const AtomType *at1,
                                const AtomType *at2);
    
    //! calculates and returns the UFF force constant for a bond
    /*!
      \param restLength  the rest length of the bond
      \param at1  pointer to the AtomType for atom 1
      \param at2  pointer to the AtomType for atom 2
      \return the force constant
    */
    RealType calcBondForceConstant(RealType restLength,
                                   const AtomType *at1,
                                   const AtomType *at2);
 
    //! Calculate the force constant for an angle bend
    /*!
      The angle is between atom1 - atom2 - atom3
      \param theta0      the preferred value of the angle (in radians)
      \param bondOrder12 order of the bond between atoms 1 and 2 (as a RealType)
      \param bondOrder23 order of the bond between atoms 2 and 3 (as a RealType)
      \param at1   pointer to the AtomType for atom 1
      \param at2   pointer to the AtomType for atom 2
      \param at3   pointer to the AtomType for atom 3
    */
    RealType calcAngleForceConstant(RealType theta0, RealType bondOrder12,
                                    RealType bondOrder23,
                                    const AtomType *at1,
                                    const AtomType *at2,
                                    const AtomType *at3);
    
    //! calculate default values of the torsion parameters.
    /*!
      see the constructor for an explanation of the arguments
    */
    void calcTorsionParams(RealType bondOrder23, int atNum2, int atNum3,
                           RDKit::Atom::HybridizationType hyb2,
                           RDKit::Atom::HybridizationType hyb3,
                           const AtomType *at2,
                           const AtomType *at3, bool endAtomIsSP2);
 
 
    bool isInGroup6(int num);
    
    RealType equation17(RealType bondOrder23,
                        const AtomType *at2, const AtomType *at3);
    
    //! calculates and returns the cosine of the Y angle in an improper torsion
    //! (see UFF paper, equation 19)
    RealType calculateCosY(const Vector3d &iPoint,
                           const Vector3d &jPoint,
                           const Vector3d &kPoint,
                           const Vector3d &lPoint);
 
    //! calculates and returns the UFF force constant for an improper torsion
    /*!
      \param at2AtomicNum   atomic number for atom 2
      \param isCBoundToO    boolean flag; true if atom 2 is sp2 carbon bound to sp2
      oxygen
      \return the force constant
    */
    void calcInversionCoefficientsAndForceConstant(int at2AtomicNum,
                                                   bool isCBoundToO);
 
    //! calculates and returns the UFF minimum position for a vdW contact
    /*!
      \param at1  pointer to the AtomType for atom 1
      \param at2  pointer to the AtomType for atom 2
      \return the position of the minimum
    */
    RealType calcNonbondedMinimum(const AtomType *at1,
                                  const AtomType *at2);
 
    //! calculates and returns the UFF well depth for a vdW contact
    /*!
      \param at1  pointer to the AtomType for atom 1
      \param at2  pointer to the AtomType for atom 2
      \return the depth of the well
    */
    RealType calcNonbondedDepth(const AtomType *at1,
                                const AtomType *at2);
  }
}
#endif