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-2025.
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.nonbonded.pme;
39  
40  import ffx.potential.parameters.ForceField;
41  import ffx.potential.parameters.ForceField.ELEC_FORM;
42  import ffx.utilities.FFXProperty;
43  
44  import java.util.logging.Logger;
45  
46  import static ffx.potential.parameters.ChargeType.DEFAULT_CHG_12_SCALE;
47  import static ffx.potential.parameters.ChargeType.DEFAULT_CHG_13_SCALE;
48  import static ffx.potential.parameters.ChargeType.DEFAULT_CHG_14_SCALE;
49  import static ffx.potential.parameters.ChargeType.DEFAULT_CHG_15_SCALE;
50  import static ffx.potential.parameters.ForceField.ELEC_FORM.PAM;
51  import static ffx.potential.parameters.MultipoleType.DEFAULT_MPOLE_12_SCALE;
52  import static ffx.potential.parameters.MultipoleType.DEFAULT_MPOLE_13_SCALE;
53  import static ffx.potential.parameters.MultipoleType.DEFAULT_MPOLE_14_SCALE;
54  import static ffx.potential.parameters.MultipoleType.DEFAULT_MPOLE_15_SCALE;
55  import static ffx.potential.parameters.PolarizeType.DEFAULT_DIRECT_11_SCALE;
56  import static ffx.potential.parameters.PolarizeType.DEFAULT_DIRECT_12_SCALE;
57  import static ffx.potential.parameters.PolarizeType.DEFAULT_DIRECT_13_SCALE;
58  import static ffx.potential.parameters.PolarizeType.DEFAULT_DIRECT_14_SCALE;
59  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_12_INTRA;
60  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_12_SCALE;
61  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_13_INTRA;
62  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_13_SCALE;
63  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_14_INTRA;
64  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_14_SCALE;
65  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_15_INTRA;
66  import static ffx.potential.parameters.PolarizeType.DEFAULT_POLAR_15_SCALE;
67  import static ffx.utilities.PropertyGroup.ElectrostaticsFunctionalForm;
68  import static java.lang.String.format;
69  
70  /**
71   * Scale factors and masking rules for electrostatics.
72   */
73  public class ScaleParameters {
74  
75    private static final Logger logger = Logger.getLogger(ScaleParameters.class.getName());
76  
77    /**
78     * The interaction energy between 1-2 multipoles is scaled by m12scale.
79     */
80    @FFXProperty(name = "mpole-12-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
81        description = """
82            Provides a multiplicative scale factor that is applied to permanent atomic multipole
83            electrostatic interactions between 1-2 connected atoms, i.e., atoms that are directly bonded.
84            The default value of 0.0 is used, if the mpole-12-scale property is not given
85            in either the parameter file or the property file.
86            """)
87    @FFXProperty(name = "chg-12-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
88        description = """
89            Provides a multiplicative scale factor that is applied to charge-charge electrostatic
90            interactions between 1-2 connected atoms, i.e., atoms that are directly bonded.
91            The default value of 0.0 is used, if the chg-12-scale keyword is not given
92            in either the parameter file or the property file.
93            """)
94    public final double m12scale;
95  
96    /**
97     * The interaction energy between 1-3 multipoles is scaled by m13scale.
98     */
99    @FFXProperty(name = "mpole-13-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
100       description = """
101           Provides a multiplicative scale factor that is applied to permanent atomic multipole
102           electrostatic interactions between 1-3 connected atoms, i.e., atoms separated by two covalent bonds.
103           The default value of 0.0 is used, if the mpole-13-scale keyword is not given
104           in either the parameter file or the property file.
105           """)
106   @FFXProperty(name = "chg-13-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
107       description = """
108           Provides a multiplicative scale factor that is applied to charge-charge electrostatic
109           interactions between 1-3 connected atoms, i.e., atoms separated by two covalent bonds.
110           The default value of 0.0 is used, if the chg-13-scale keyword is not given
111           in either the parameter file or the property file.
112           """)
113   public final double m13scale;
114 
115   /**
116    * The interaction energy between 1-4 multipoles is scaled by m14scale.
117    */
118   @FFXProperty(name = "mpole-14-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
119       description = """
120           Provides a multiplicative scale factor that is applied to permanent atomic multipole
121           electrostatic interactions between 1-4 connected atoms, i.e., atoms separated by three covalent bonds.
122           The default value of 1.0 is used, if the mpole-14-scale keyword is not given
123           in either the parameter file or the property file.
124           """)
125   @FFXProperty(name = "chg-14-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
126       description = """
127           Provides a multiplicative scale factor that is applied to charge-charge electrostatic
128           interactions between 1-4 connected atoms, i.e., atoms separated by three covalent bonds.
129           The default value of 1.0 is used, if the chg-14-scale keyword is not given
130           in either the parameter file or the property file.
131           """)
132   public final double m14scale;
133 
134   /**
135    * The interaction energy between 1-5 multipoles is scaled by m15scale.
136    */
137   @FFXProperty(name = "mpole-15-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
138       description = """
139           Provides a multiplicative scale factor that is applied to permanent atomic multipole
140           electrostatic interactions between 1-5 connected atoms, i.e., atoms separated by four covalent bonds.
141           The default value of 1.0 is used, if the mpole-15-scale keyword is not given
142           in either the parameter file or the property file.
143           """)
144   @FFXProperty(name = "chg-15-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
145       description = """
146           Provides a multiplicative scale factor that is applied to charge-charge electrostatic
147           interactions between 1-5 connected atoms, i.e., atoms separated by four covalent bonds.
148           The default value of 1.0 is used, if the chg-15-scale keyword is not given
149           in either the parameter file or the property file.
150           """)
151   public final double m15scale;
152 
153   /**
154    * DIRECT-11-SCALE factor.
155    */
156   @FFXProperty(name = "direct-11-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
157       description = """
158           Provides a multiplicative scale factor that is applied to the permanent (direct) field
159           due to atoms within a polarization group during an induced dipole calculation,
160           i.e., atoms that are in the same polarization group as the atom being polarized.
161           The default value of 0.0 is used, if the direct-11-scale keyword is not given
162           in either the parameter file or the property file.
163           """)
164   public final double d11scale;
165 
166   /**
167    * The DIRECT_12_SCALE factor is assumed to be 1.0. If this assumption is violated by a keyword,
168    * FFX will exit.
169    */
170   @FFXProperty(name = "direct-12-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
171       description = """
172           Provides a multiplicative scale factor that is applied to the permanent (direct) field
173           due to atoms in 1-2 polarization groups during an induced dipole calculation,
174           i.e., atoms that are in polarization groups directly connected to the group containing the atom being polarized.
175           The default value of 0.0 is used, if the direct-12-scale keyword is not given
176           in either the parameter file or the property file.
177           """)
178   public final double d12scale;
179 
180   /**
181    * The DIRECT_13_SCALE factor is assumed to be 1.0. If this assumption is violated by a keyword,
182    * FFX will exit.
183    */
184   @FFXProperty(name = "direct-13-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
185       description = """
186           Provides a multiplicative scale factor that is applied to the permanent (direct) field
187           due to atoms in 1-3 polarization groups during an induced dipole calculation,
188           i.e., atoms that are in polarization groups separated by one group from the group containing the atom being polarized.
189           The default value of 0.0 is used, if the direct-13-scale keyword is not given
190           in either the parameter file or the property file.
191           """)
192   public final double d13scale;
193 
194   /**
195    * The DIRECT_14_SCALE factor is assumed to be 1.0. If this assumption is violated by a keyword,
196    * FFX will exit.
197    */
198   @FFXProperty(name = "direct-14-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
199       description = """
200           Provides a multiplicative scale factor that is applied to the permanent (direct) field
201           due to atoms in 1-4 polarization groups during an induced dipole calculation,
202           i.e., atoms that are in polarization groups separated by two groups from the group containing the atom being polarized.
203           The default value of 1.0 is used, if the direct-14-scale keyword is not given
204           in either the parameter file or the property file.
205           """)
206   public final double d14scale;
207 
208   /**
209    * The interaction energy between a permanent multipole and polarizable site that are 1-2 is scaled
210    * by p12scale.
211    */
212   @FFXProperty(name = "polar-12-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
213       description = """
214           Provides a multiplicative scale factor that is applied to polarization interactions
215           between 1-2 connected atoms located in different polarization groups.
216           The default value of 0.0 is used, if the polar-12-scale keyword is not given
217           in either the parameter file or the property file.
218           """)
219   public final double p12scale;
220 
221   /**
222    * The interaction energy between a permanent multipole and polarizable site that are 1-3 is scaled
223    * by p13scale.
224    */
225   @FFXProperty(name = "polar-13-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
226       description = """ 
227           Provides a multiplicative scale factor that is applied to polarization interactions
228           between 1-3 connected atoms located in different polarization groups.
229           The default value of 0.0 is used, if the polar-13-scale keyword is not given
230           in either the parameter file or the property file.
231           """)
232   public final double p13scale;
233 
234   /**
235    * The interaction energy between a permanent multipole and polarizable site that are 1-4 is scaled
236    * by p14scale.
237    */
238   @FFXProperty(name = "polar-14-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
239       description = """
240           Provides a multiplicative scale factor that is applied to polarization interactions
241           between 1-4 connected atoms located in different polarization groups.
242           The default value of 1.0 is used, if the polar-14-scale keyword is not given
243           in either the parameter file or the property file.
244           """)
245   public final double p14scale;
246 
247   /**
248    * The interaction energy between a permanent multipole and polarizable site that are 1-5 is scaled
249    * by p15scale. Only 1.0 is supported.
250    */
251   @FFXProperty(name = "polar-15-scale", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
252       description = """
253           Provides a multiplicative scale factor that is applied to polarization interactions
254           between 1-5 connected atoms located in different polarization groups.
255           The default value of 1.0 is used, if the polar-15-scale keyword is not given
256           in either the parameter file or the property file.
257           """)
258   public final double p15scale;
259 
260   /**
261    * An intra-12-scale factor other than 0.0 is not supported and will cause FFX to exit.
262    */
263   @FFXProperty(name = "polar-12-intra", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
264       description = """
265           Provides a multiplicative scale factor that is applied to polarization interactions
266           between 1-2 connected atoms located in the same polarization group.
267           The default value of 0.0 is used, if the polar-12-intra keyword is not given
268           in either the parameter file or the property file.
269           """)
270   public final double intra12Scale;
271   /**
272    * An intra-13-scale factor other than 0.0 is not supported and will cause FFX to exit.
273    */
274   @FFXProperty(name = "polar-13-intra", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.0",
275       description = """
276           Provides a multiplicative scale factor that is applied to polarization interactions
277           between 1-3 connected atoms located in the same polarization group.
278           The default value of 0.0 is used, if the polar-13-intra keyword is not given
279           in either the parameter file or the property file.
280           """)
281   public final double intra13Scale;
282   /**
283    * Provides a multiplicative scale factor that is applied to polarization interactions between 1-4
284    * connected atoms located in the same polarization group.
285    */
286   @FFXProperty(name = "polar-14-intra", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "0.5",
287       description = """
288           Provides a multiplicative scale factor that is applied to polarization interactions
289           between 1-4 connected atoms located in the same polarization group.
290           The default value of 0.5 is used, if the polar-14-intra keyword is not given
291           in either the parameter file or the property file.
292           """)
293   public final double intra14Scale;
294   /**
295    * An intra-15-scale factor other than 1.0 is not supported and will cause FFX to exit.
296    */
297   @FFXProperty(name = "polar-15-intra", propertyGroup = ElectrostaticsFunctionalForm, defaultValue = "1.0",
298       description = """
299           Provides a multiplicative scale factor that is applied to polarization interactions
300           between 1-5 connected atoms located in the same polarization group.
301           The default value of 1.0 is used, if the polar-15-intra keyword is not given
302           in either the parameter file or the property file.
303           """)
304   public final double intra15Scale;
305 
306   public ScaleParameters(ELEC_FORM elecForm, ForceField forceField) {
307     if (elecForm == PAM) {
308       double m12 = forceField.getDouble("MPOLE_12_SCALE", DEFAULT_MPOLE_12_SCALE);
309       if (m12 > 1.0) {
310         m12 = 1.0 / m12;
311       }
312       m12scale = m12;
313       double m13 = forceField.getDouble("MPOLE_13_SCALE", DEFAULT_MPOLE_13_SCALE);
314       if (m13 > 1.0) {
315         m13 = 1.0 / m13;
316       }
317       m13scale = m13;
318       double m14 = forceField.getDouble("MPOLE_14_SCALE", DEFAULT_MPOLE_14_SCALE);
319       if (m14 > 1.0) {
320         m14 = 1.0 / m14;
321       }
322       m14scale = m14;
323       double m15 = forceField.getDouble("MPOLE_15_SCALE", DEFAULT_MPOLE_15_SCALE);
324       if (m15 > 1.0) {
325         m15 = 1.0 / m15;
326       }
327       m15scale = m15;
328     } else {
329       double m12 = forceField.getDouble("CHG_12_SCALE", DEFAULT_CHG_12_SCALE);
330       if (m12 > 1.0) {
331         m12 = 1.0 / m12;
332       }
333       m12scale = m12;
334       double m13 = forceField.getDouble("CHG_13_SCALE", DEFAULT_CHG_13_SCALE);
335       if (m13 > 1.0) {
336         m13 = 1.0 / m13;
337       }
338       m13scale = m13;
339       double m14 = forceField.getDouble("CHG_14_SCALE", DEFAULT_CHG_14_SCALE);
340       if (m14 > 1.0) {
341         m14 = 1.0 / m14;
342       }
343       m14scale = m14;
344       double m15 = forceField.getDouble("CHG_15_SCALE", DEFAULT_CHG_15_SCALE);
345       if (m15 > 1.0) {
346         m15 = 1.0 / m15;
347       }
348       m15scale = m15;
349     }
350 
351     // Multiplicative scale factors applied to polarization interactions between connected
352     // atoms located in the same polarization group.
353     intra12Scale = forceField.getDouble("POLAR_12_INTRA", DEFAULT_POLAR_12_INTRA);
354     if (intra12Scale != 0.0) {
355       logger.severe(format(" Unsupported polar-12-intra parameter: %8.6f", intra12Scale));
356     }
357     intra13Scale = forceField.getDouble("POLAR_13_INTRA", DEFAULT_POLAR_13_INTRA);
358     if (intra13Scale != 0.0) {
359       logger.severe(format(" Unsupported polar-13-intra parameter: %8.6f", intra13Scale));
360     }
361     intra14Scale = forceField.getDouble("POLAR_14_INTRA", DEFAULT_POLAR_14_INTRA);
362     intra15Scale = forceField.getDouble("POLAR_15_INTRA", DEFAULT_POLAR_15_INTRA);
363     if (intra15Scale != 1.0) {
364       logger.severe(format(" Unsupported polar-15-intra parameter: %8.6f", intra15Scale));
365     }
366 
367     // Polarization groups masking rules.
368     d11scale = forceField.getDouble("DIRECT_11_SCALE", DEFAULT_DIRECT_11_SCALE);
369     d12scale = forceField.getDouble("DIRECT_12_SCALE", DEFAULT_DIRECT_12_SCALE);
370     d13scale = forceField.getDouble("DIRECT_13_SCALE", DEFAULT_DIRECT_13_SCALE);
371     d14scale = forceField.getDouble("DIRECT_14_SCALE", DEFAULT_DIRECT_14_SCALE);
372     if (d12scale != 1.0) {
373       logger.severe(format(" Unsupported direct-12-scale parameter: %8.6f", d12scale));
374     }
375     if (d13scale != 1.0) {
376       logger.severe(format(" Unsupported direct-13-scale parameter: %8.6f", d13scale));
377     }
378     if (d14scale != 1.0) {
379       logger.severe(format(" Unsupported direct-14-scale parameter: %8.6f", d14scale));
380     }
381 
382     // Polarization energy masking rules.
383     p12scale = forceField.getDouble("POLAR_12_SCALE", DEFAULT_POLAR_12_SCALE);
384     p13scale = forceField.getDouble("POLAR_13_SCALE", DEFAULT_POLAR_13_SCALE);
385     p14scale = forceField.getDouble("POLAR_14_SCALE", DEFAULT_POLAR_14_SCALE);
386     p15scale = forceField.getDouble("POLAR_15_SCALE", DEFAULT_POLAR_15_SCALE);
387     if (p15scale != 1.0) {
388       logger.severe(format(" Unsupported polar-15-scale parameter: %8.6f", p15scale));
389     }
390   }
391 }