Added FAQ links to error messages (#3600)

* Added FAQ links to error messages

* Added missing Windows export

openmmapi/include/openmm/internal/Messages.h

+#ifndef OPENMM_MESSAGES_H_
+#define OPENMM_MESSAGES_H_
+
+/* -------------------------------------------------------------------------- *
+ *                                   OpenMM                                   *
+ * -------------------------------------------------------------------------- *
+ * This is part of the OpenMM molecular simulation toolkit originating from   *
+ * Simbios, the NIH National Center for Physics-Based Simulation of           *
+ * Biological Structures at Stanford, funded under the NIH Roadmap for        *
+ * Medical Research, grant U54 GM072970. See https://simtk.org.               *
+ *                                                                            *
+ * Portions copyright (c) 2022 Stanford University and the Authors.           *
+ * Authors: Peter Eastman                                                     *
+ * Contributors:                                                              *
+ *                                                                            *
+ * Permission is hereby granted, free of charge, to any person obtaining a    *
+ * copy of this software and associated documentation files (the "Software"), *
+ * to deal in the Software without restriction, including without limitation  *
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
+ * and/or sell copies of the Software, and to permit persons to whom the      *
+ * Software is furnished to do so, subject to the following conditions:       *
+ *                                                                            *
+ * The above copyright notice and this permission notice shall be included in *
+ * all copies or substantial portions of the Software.                        *
+ *                                                                            *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
+ * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
+ * -------------------------------------------------------------------------- */
+
+#include "windowsExport.h"
+#include <string>
+
+namespace OpenMM {
+
+/**
+ * This class provides a central place to store strings that get used in many
+ * places, such as common error messages.
+ */
+class OPENMM_EXPORT Messages {
+public:
+    static std::string cutoffTooLarge;
+};
+
+} // namespace OpenMM
+
+#endif /*OPENMM_MESSAGES_H_*/

openmmapi/src/CustomGBForceImpl.cpp

@@ -32,6 +32,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/CustomGBForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/kernels.h"
 #include <sstream>
 
@@ -100,7 +101,7 @@ void CustomGBForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("CustomGBForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("CustomGBForce: "+Messages::cutoffTooLarge);
     }
     kernel.getAs<CalcCustomGBForceKernel>().initialize(context.getSystem(), owner);
 }

openmmapi/src/CustomHbondForceImpl.cpp

@@ -32,6 +32,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/CustomHbondForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/kernels.h"
 #include "lepton/Operation.h"
 #include "lepton/Parser.h"
@@ -173,7 +174,7 @@ void CustomHbondForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("CustomHbondForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("CustomHbondForce: "+Messages::cutoffTooLarge);
     }
     kernel.getAs<CalcCustomHbondForceKernel>().initialize(context.getSystem(), owner);
 }

openmmapi/src/CustomManyParticleForceImpl.cpp

@@ -32,6 +32,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/CustomManyParticleForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/kernels.h"
 #include "lepton/Operation.h"
 #include "lepton/Parser.h"
@@ -129,7 +130,7 @@ void CustomManyParticleForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("CustomManyParticleForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("CustomManyParticleForce: "+Messages::cutoffTooLarge);
     }
     kernel.getAs<CalcCustomManyParticleForceKernel>().initialize(context.getSystem(), owner);
 }

openmmapi/src/CustomNonbondedForceImpl.cpp

@@ -35,6 +35,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/CustomNonbondedForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/internal/SplineFitter.h"
 #include "openmm/kernels.h"
 #include "ReferenceTabulatedFunction.h"
@@ -110,7 +111,7 @@ void CustomNonbondedForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("CustomNonbondedForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("CustomNonbondedForce: "+Messages::cutoffTooLarge);
     }
     // Check that all interaction groups only specify particles that have been defined.
     for (int group = 0; group < owner.getNumInteractionGroups(); group++) {

openmmapi/src/GBSAOBCForceImpl.cpp

@@ -32,6 +32,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/GBSAOBCForceImpl.h"
 #include "openmm/internal/ContextImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/kernels.h"
 #include <vector>
 
@@ -50,7 +51,7 @@ void GBSAOBCForceImpl::initialize(ContextImpl& context) {
         context.getSystem().getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("GBSAOBCForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("GBSAOBCForce: "+Messages::cutoffTooLarge);
     }
     for (int i = 0; i < owner.getNumParticles(); i++) {
         double charge, radius, scalingFactor;

openmmapi/src/GayBerneForceImpl.cpp

@@ -32,6 +32,7 @@
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/GayBerneForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/kernels.h"
 #include <set>
 #include <sstream>
@@ -115,7 +116,7 @@ void GayBerneForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("GayBerneForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("GayBerneForce: "+Messages::cutoffTooLarge);
     }
     kernel.getAs<CalcGayBerneForceKernel>().initialize(context.getSystem(), owner);
 }

openmmapi/src/Messages.cpp

+/* -------------------------------------------------------------------------- *
+ *                                   OpenMM                                   *
+ * -------------------------------------------------------------------------- *
+ * This is part of the OpenMM molecular simulation toolkit originating from   *
+ * Simbios, the NIH National Center for Physics-Based Simulation of           *
+ * Biological Structures at Stanford, funded under the NIH Roadmap for        *
+ * Medical Research, grant U54 GM072970. See https://simtk.org.               *
+ *                                                                            *
+ * Portions copyright (c) 2022 Stanford University and the Authors.           *
+ * Authors: Peter Eastman                                                     *
+ * Contributors:                                                              *
+ *                                                                            *
+ * Permission is hereby granted, free of charge, to any person obtaining a    *
+ * copy of this software and associated documentation files (the "Software"), *
+ * to deal in the Software without restriction, including without limitation  *
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
+ * and/or sell copies of the Software, and to permit persons to whom the      *
+ * Software is furnished to do so, subject to the following conditions:       *
+ *                                                                            *
+ * The above copyright notice and this permission notice shall be included in *
+ * all copies or substantial portions of the Software.                        *
+ *                                                                            *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
+ * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
+ * -------------------------------------------------------------------------- */
+
+#include "openmm/internal/Messages.h"
+
+using namespace OpenMM;
+using namespace std;
+
+string Messages::cutoffTooLarge = "The cutoff distance cannot be greater than half the periodic box size.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#boxsize";
\ No newline at end of file

openmmapi/src/NonbondedForceImpl.cpp

@@ -34,6 +34,7 @@
 #endif
 #include "openmm/OpenMMException.h"
 #include "openmm/internal/ContextImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/internal/NonbondedForceImpl.h"
 #include "openmm/kernels.h"
 #include <cmath>
@@ -127,7 +128,7 @@ void NonbondedForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("NonbondedForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("NonbondedForce: "+Messages::cutoffTooLarge);
         if (owner.getNonbondedMethod() == NonbondedForce::Ewald && (boxVectors[1][0] != 0.0 || boxVectors[2][0] != 0.0 || boxVectors[2][1] != 0))
             throw OpenMMException("NonbondedForce: Ewald is not supported with non-rectangular boxes.  Use PME instead.");
     }

platforms/common/src/ComputeContext.cpp

@@ -512,7 +512,7 @@ void ComputeContext::reorderAtomsImpl() {
             molPos[i].y *= invNumAtoms;
             molPos[i].z *= invNumAtoms;
             if (molPos[i].x != molPos[i].x)
-                throw OpenMMException("Particle coordinate is nan");
+                throw OpenMMException("Particle coordinate is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan");
         }
         if (getNonbondedUtilities().getUsePeriodic()) {
             // Move each molecule position into the same box.

platforms/cpu/src/CpuKernels.cpp

@@ -229,7 +229,7 @@ void CpuCalcForcesAndEnergyKernel::beginComputation(ContextImpl& context, bool i
     });
     data.threads.waitForThreads();
     if (!positionsValid)
-        throw OpenMMException("Particle coordinate is nan");
+        throw OpenMMException("Particle coordinate is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan");
 
     // Determine whether we need to recompute the neighbor list.
         

plugins/amoeba/openmmapi/src/AmoebaMultipoleForceImpl.cpp

@@ -31,6 +31,7 @@
 
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/AmoebaMultipoleForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/amoebaKernels.h"
 #include <stdio.h>
 
@@ -61,7 +62,7 @@ void AmoebaMultipoleForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("AmoebaMultipoleForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("AmoebaMultipoleForce: "+Messages::cutoffTooLarge);
     }
 
     double quadrupoleValidationTolerance = 1.0e-05;

plugins/amoeba/openmmapi/src/AmoebaVdwForceImpl.cpp

@@ -34,6 +34,7 @@
 #endif
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/AmoebaVdwForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/amoebaKernels.h"
 #include <map>
 #include <cmath>
@@ -60,7 +61,7 @@ void AmoebaVdwForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("AmoebaVdwForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("AmoebaVdwForce: "+Messages::cutoffTooLarge);
     }   
 
     kernel = context.getPlatform().createKernel(CalcAmoebaVdwForceKernel::Name(), context);

plugins/amoeba/openmmapi/src/HippoNonbondedForceImpl.cpp

@@ -31,6 +31,7 @@
 
 #include "openmm/internal/ContextImpl.h"
 #include "openmm/internal/HippoNonbondedForceImpl.h"
+#include "openmm/internal/Messages.h"
 #include "openmm/amoebaKernels.h"
 
 using namespace OpenMM;
@@ -55,7 +56,7 @@ void HippoNonbondedForceImpl::initialize(ContextImpl& context) {
         system.getDefaultPeriodicBoxVectors(boxVectors[0], boxVectors[1], boxVectors[2]);
         double cutoff = owner.getCutoffDistance();
         if (cutoff > 0.5*boxVectors[0][0] || cutoff > 0.5*boxVectors[1][1] || cutoff > 0.5*boxVectors[2][2])
-            throw OpenMMException("HippoNonbondedForce: The cutoff distance cannot be greater than half the periodic box size.");
+            throw OpenMMException("HippoNonbondedForce: "+Messages::cutoffTooLarge);
     }
 
     double quadrupoleValidationTolerance = 1.0e-05;

wrappers/python/openmm/app/dcdfile.py

@@ -122,9 +122,9 @@ class DCDFile(object):
         if is_quantity(positions):
             positions = positions.value_in_unit(nanometers)
         if any(math.isnan(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is NaN')
+            raise ValueError('Particle position is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         if any(math.isinf(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is infinite')
+            raise ValueError('Particle position is infinite.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         file = self._file
 
         self._modelCount += 1

wrappers/python/openmm/app/forcefield.py

@@ -1424,7 +1424,7 @@ class ForceField(object):
                             # We successfully generated a residue template.  Break out of the for loop.
                             break
             if matches is None:
-                raise ValueError('No template found for residue %d (%s).  %s' % (res.index+1, res.name, _findMatchErrors(self, res)))
+                raise ValueError('No template found for residue %d (%s).  %s  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#template' % (res.index+1, res.name, _findMatchErrors(self, res)))
             else:
                 if recordParameters:
                     data.recordMatchedAtomParameters(res, template, matches)

wrappers/python/openmm/app/pdbfile.py

@@ -340,9 +340,9 @@ class PDBFile(object):
         if is_quantity(positions):
             positions = positions.value_in_unit(angstroms)
         if any(math.isnan(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is NaN')
+            raise ValueError('Particle position is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         if any(math.isinf(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is infinite')
+            raise ValueError('Particle position is infinite.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         nonHeterogens = PDBFile._standardResidues[:]
         nonHeterogens.remove('HOH')
         atomIndex = 1

wrappers/python/openmm/app/pdbxfile.py

@@ -404,9 +404,9 @@ class PDBxFile(object):
         if is_quantity(positions):
             positions = positions.value_in_unit(angstroms)
         if any(math.isnan(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is NaN')
+            raise ValueError('Particle position is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         if any(math.isinf(norm(pos)) for pos in positions):
-            raise ValueError('Particle position is infinite')
+            raise ValueError('Particle position is infinite.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
         nonHeterogens = PDBFile._standardResidues[:]
         nonHeterogens.remove('HOH')
         atomIndex = 1

wrappers/python/openmm/app/statedatareporter.py

@@ -362,9 +362,9 @@ class StateDataReporter(object):
         if self._needEnergy:
             energy = (state.getKineticEnergy()+state.getPotentialEnergy()).value_in_unit(unit.kilojoules_per_mole)
             if math.isnan(energy):
-                raise ValueError('Energy is NaN')
+                raise ValueError('Energy is NaN.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
             if math.isinf(energy):
-                raise ValueError('Energy is infinite')
+                raise ValueError('Energy is infinite.  For more information, see https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions#nan')
 
     def __del__(self):
         if self._openedFile: