View Javadoc
1   // ******************************************************************************
2   //
3   // Title:       Force Field X.
4   // Description: Force Field X - Software for Molecular Biophysics.
5   // Copyright:   Copyright (c) Michael J. Schnieders 2001-2024.
6   //
7   // This file is part of Force Field X.
8   //
9   // Force Field X is free software; you can redistribute it and/or modify it
10  // under the terms of the GNU General Public License version 3 as published by
11  // the Free Software Foundation.
12  //
13  // Force Field X is distributed in the hope that it will be useful, but WITHOUT
14  // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  // FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
16  // details.
17  //
18  // You should have received a copy of the GNU General Public License along with
19  // Force Field X; if not, write to the Free Software Foundation, Inc., 59 Temple
20  // Place, Suite 330, Boston, MA 02111-1307 USA
21  //
22  // Linking this library statically or dynamically with other modules is making a
23  // combined work based on this library. Thus, the terms and conditions of the
24  // GNU General Public License cover the whole combination.
25  //
26  // As a special exception, the copyright holders of this library give you
27  // permission to link this library with independent modules to produce an
28  // executable, regardless of the license terms of these independent modules, and
29  // to copy and distribute the resulting executable under terms of your choice,
30  // provided that you also meet, for each linked independent module, the terms
31  // and conditions of the license of that module. An independent module is a
32  // module which is not derived from or based on this library. If you modify this
33  // library, you may extend this exception to your version of the library, but
34  // you are not obligated to do so. If you do not wish to do so, delete this
35  // exception statement from your version.
36  //
37  // ******************************************************************************
38  package ffx.potential.bonded;
39  
40  import static org.apache.commons.math3.util.FastMath.acos;
41  import static org.apache.commons.math3.util.FastMath.max;
42  import static org.apache.commons.math3.util.FastMath.min;
43  import static org.apache.commons.math3.util.FastMath.sqrt;
44  import static org.apache.commons.math3.util.FastMath.toDegrees;
45  
46  import ffx.numerics.atomic.AtomicDoubleArray3D;
47  import ffx.potential.parameters.ForceField;
48  import ffx.potential.parameters.StretchBendType;
49  
50  import java.io.Serial;
51  import java.util.logging.Logger;
52  
53  /**
54   * The StretchBend class represents a Stretch-Bend formed between three linearly bonded atoms.
55   *
56   * @author Michael J. Schnieders
57   * @since 1.0
58   */
59  public class StretchBend extends BondedTerm implements Comparable<BondedTerm> {
60  
61    @Serial
62    private static final long serialVersionUID = 1L;
63  
64    private static final Logger logger = Logger.getLogger(StretchBend.class.getName());
65    /** Equilibrium angle. */
66    public double angleEq;
67    /** First equilibrium bond distance. */
68    public double bond0Eq;
69    /** Second equilibrium bond distance. */
70    public double bond1Eq;
71    /** Angle this Stretch-Bend is based on. */
72    protected final Angle angle;
73    /** Force constant. */
74    public double force0, force1;
75    /** Force field parameters to compute the Stretch-Bend energy. */
76    private StretchBendType stretchBendType = null;
77    /** Rigid scale factor to apply to the force constant. */
78    private double rigidScale = 1.0;
79  
80    /**
81     * Constructor for the Stretch-Bend class.
82     *
83     * @param a The Angle that this stretch-bend is based on.
84     */
85    public StretchBend(Angle a) {
86      super();
87      angle = a;
88      atoms = a.atoms;
89      bonds = a.bonds;
90      angleEq = angle.angleType.angle[angle.nh];
91      bond0Eq = bonds[0].bondType.distance;
92      bond1Eq = bonds[1].bondType.distance;
93      setID_Key(false);
94    }
95  
96    /**
97     * Attempt to create a new StretchBend if a StretchBendType exists for the specified Angle.
98     *
99     * @param angle the Angle used to create the StretchBend.
100    * @param forceField the ForceField parameters to use.
101    * @return a new StretchBend, or null.
102    */
103   static StretchBend stretchBendFactory(Angle angle, ForceField forceField) {
104     StretchBendType stretchBendType = forceField.getStretchBendType(angle.getAngleType().getKey());
105     if (stretchBendType == null) {
106       return null;
107     }
108     StretchBend stretchBend = new StretchBend(angle);
109     stretchBend.setStretchBendType(stretchBendType);
110     return stretchBend;
111   }
112 
113   /** {@inheritDoc} */
114   @Override
115   public int compareTo(BondedTerm sb) {
116     if (!sb.getClass().isInstance(this)) {
117       return super.compareTo(sb);
118     }
119     return angle.compareTo(((StretchBend) sb).angle);
120   }
121 
122   /**
123    * {@inheritDoc}
124    *
125    * <p>Evaluate the Stretch-Bend energy.
126    */
127   @Override
128   public double energy(boolean gradient, int threadID, AtomicDoubleArray3D grad, AtomicDoubleArray3D lambdaGrad) {
129     energy = 0.0;
130     value = 0.0;
131     // Only compute this term if at least one atom is being used.
132     if (!getUse()) {
133       return energy;
134     }
135     var atomA = atoms[0];
136     var atomB = atoms[1];
137     var atomC = atoms[2];
138     var ia = atomA.getIndex() - 1;
139     var ib = atomB.getIndex() - 1;
140     var ic = atomC.getIndex() - 1;
141     var va = atomA.getXYZ();
142     var vb = atomB.getXYZ();
143     var vc = atomC.getXYZ();
144     var vab = va.sub(vb);
145     var vcb = vc.sub(vb);
146     var rab2 = vab.length2();
147     var rcb2 = vcb.length2();
148     if (rab2 != 0.0 && rcb2 != 0.0) {
149       var rab = sqrt(rab2);
150       var rcb = sqrt(rcb2);
151       var vp = vcb.X(vab);
152       var rp = max(vp.length(), 0.000001);
153       value = toDegrees(acos(min(1.0, max(-1.0, vab.dot(vcb) / (rab * rcb)))));
154       var e0 = rab - bond0Eq;
155       var e1 = rcb - bond1Eq;
156       var dt = value - angleEq;
157       var dr = force0 * e0 + force1 * e1;
158       var prefactor = rigidScale;
159       energy = prefactor * dr * dt;
160       if (gradient) {
161         var vdta = vab.X(vp).scaleI(-prefactor * dr * toDegrees(1.0 / (rab2 * rp)));
162         var vdtc = vcb.X(vp).scaleI(prefactor * dr * toDegrees(1.0 / (rcb2 * rp)));
163         var ga = vdta.addI(vab.scaleI(prefactor * force0 * dt / rab));
164         var gc = vdtc.addI(vcb.scaleI(prefactor * force1 * dt / rcb));
165         grad.add(threadID, ia, ga);
166         grad.sub(threadID, ib, ga.add(gc));
167         grad.add(threadID, ic, gc);
168       }
169     }
170     return energy;
171   }
172 
173   /** log */
174   public void log() {
175     logger.info(String.format(" %s %6d-%s %6d-%s %6d-%s" + "%7.4f %10.4f", "Stretch-Bend",
176         atoms[0].getIndex(), atoms[0].getAtomType().name, atoms[1].getIndex(),
177         atoms[1].getAtomType().name, atoms[2].getIndex(), atoms[2].getAtomType().name, value,
178         energy));
179   }
180 
181   /**
182    * Setter for the field <code>rigidScale</code>.
183    *
184    * @param rigidScale a double.
185    */
186   public void setRigidScale(double rigidScale) {
187     this.rigidScale = rigidScale;
188   }
189 
190   /**
191    * Setter for the field <code>stretchBendType</code>.
192    *
193    * @param stretchBendType a {@link ffx.potential.parameters.StretchBendType} object.
194    */
195   public void setStretchBendType(StretchBendType stretchBendType) {
196     this.stretchBendType = stretchBendType;
197     // Match the atom class of the angle to the atom class of the stretch-bend type.
198     if (atoms[0].getAtomType().atomClass == stretchBendType.atomClasses[0]) {
199       force0 = stretchBendType.strbndunit * stretchBendType.forceConstants[0];
200       force1 = stretchBendType.strbndunit * stretchBendType.forceConstants[1];
201     } else {
202       force0 = stretchBendType.strbndunit * stretchBendType.forceConstants[1];
203       force1 = stretchBendType.strbndunit * stretchBendType.forceConstants[0];
204     }
205     atoms = angle.atoms;
206     bonds = angle.bonds;
207     angleEq = angle.angleType.angle[angle.nh];
208     bond0Eq = bonds[0].bondType.distance;
209     bond1Eq = bonds[1].bondType.distance;
210   }
211 
212   /**
213    * {@inheritDoc}
214    *
215    * <p>Overridden toString Method returns the Term's id.
216    */
217   @Override
218   public String toString() {
219     return String.format("%s  (%7.2f,%7.2f,%7.1f,%7.2f)", id, bonds[0].value, bonds[1].value,
220         angle.value, energy);
221   }
222 }