IMP logo
IMP Reference Guide  2.5.0
The Integrative Modeling Platform
smoothing_functions.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/smoothing_functions.h
3  * \brief Classes to smooth nonbonded interactions
4  *
5  * Copyright 2007-2015 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPATOM_SMOOTHING_FUNCTIONS_H
9 #define IMPATOM_SMOOTHING_FUNCTIONS_H
10 
11 #include <IMP/atom/atom_config.h>
12 
13 #include <IMP/base_types.h>
14 #include <IMP/Object.h>
15 #include <IMP/object_macros.h>
16 
17 IMPATOM_BEGIN_NAMESPACE
18 
19 //! Base class for smoothing nonbonded interactions as a function of distance.
20 /** The class is given the score (and optionally its first derivative)
21  at a given distance and returns a smoothed form of the score.
22  Smoothing functions are used to avoid a discontinuity in the scoring
23  function and/or its derivatives at the cutoff distance (the distance
24  threshold used by IMP::core::ClosePairsFinder), as this can lead
25  to nonphysical motions of the system. They are used by physical scoring
26  functions that drop off slowly with distance, such as CoulombPairScore,
27  in combination with a ClosePairsFinder.
28 
29  Smoothing functions usually offset the score by a constant value
30  (a shift function) or smooth it from its normal value to zero over
31  a defined range (a switch function, such as ForceSwitch).
32  */
33 class IMPATOMEXPORT SmoothingFunction : public IMP::Object {
34  public:
36 
37  //! Smooth the score at a given distance.
38  /** \return the smoothed score.
39  */
40  virtual double operator()(double score, double distance) const = 0;
41 
42  //! Smooth the score and its first derivative at a given distance.
43  /** \return a DerivativePair containing the smoothed score and its
44  first derivative.
45  */
46  virtual DerivativePair operator()(double score, double deriv,
47  double distance) const = 0;
48 
50 };
51 
52 //! Smooth interaction scores by switching the derivatives (force switch).
53 /** This function leaves the scores unaffected for distances below or equal
54  to min_distance, returns zero for distances above max_distance, and between
55  the two thresholds smoothes the score such that its first derivatives drop
56  linearly, i.e. the score is simply multiplied by \f[
57  \left\{
58  \begin{array}{ll}
59  1 & d \leq d_{min}
60  \frac{(d_{max} - d)^2 (d_{max} + 2d - 3d_{min})}
61  {(d_{max} - d_{min})^3} & d_{min} < d \leq d_{max}
62  0 & d > d_{max}
63  \end{array}
64  \right.
65  \f] where \f$d\f$ is the distance, and \f$d_{min}\f$ and \f$d_{max}\f$ are
66  the thresholds set in the ForceSwitch constructor.
67 
68  This behavior is roughly equivalent to CHARMM's force switch nonbonded
69  interaction smoothing (which is also the smoothing mechanism used
70  by MODELLER).
71 
72  \see CoulombPairScore
73  */
74 class IMPATOMEXPORT ForceSwitch : public SmoothingFunction {
75  double min_distance_, max_distance_;
76  double value_prefactor_, deriv_prefactor_;
77 
78  inline double get_value(double distance) const {
79  if (distance <= min_distance_) {
80  return 1.0;
81  } else if (distance > max_distance_) {
82  return 0.0;
83  } else {
84  double d = max_distance_ - distance;
85  return value_prefactor_ * d * d *
86  (max_distance_ + 2.0 * distance - 3.0 * min_distance_);
87  }
88  }
89 
90  inline double get_deriv(double distance) const {
91  if (distance <= min_distance_ || distance > max_distance_) {
92  return 0.0;
93  } else {
94  return deriv_prefactor_ * (max_distance_ - distance) *
95  (min_distance_ - distance);
96  }
97  }
98 
99  public:
100  ForceSwitch(double min_distance, double max_distance)
101  : min_distance_(min_distance), max_distance_(max_distance) {
102  IMP_USAGE_CHECK(max_distance > min_distance,
103  "max_distance should be greater than min_distance");
104  double dist_dif = max_distance - min_distance;
105  value_prefactor_ = 1.0 / (dist_dif * dist_dif * dist_dif);
106  deriv_prefactor_ = 6.0 * value_prefactor_;
107  }
108 
109  double operator()(double score, double distance) const {
110  double factor = get_value(distance);
111  return score * factor;
112  }
113 
114  DerivativePair operator()(double score, double deriv, double distance) const {
115  double factor = get_value(distance);
116  double deriv_factor = get_deriv(distance);
117  return std::make_pair(score * factor,
118  score * deriv_factor + deriv * factor);
119  }
120 
122 };
123 
124 IMPATOM_END_NAMESPACE
125 
126 #endif /* IMPATOM_SMOOTHING_FUNCTIONS_H */
Various general useful macros for IMP.
Basic types used by IMP.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
Common base class for heavy weight IMP objects.
Definition: Object.h:106
double operator()(double score, double distance) const
Smooth the score at a given distance.
std::pair< double, double > DerivativePair
A pair representing a function value with its first derivative.
Definition: types.h:23
A shared base class to help in debugging and things.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
Base class for smoothing nonbonded interactions as a function of distance.
Smooth interaction scores by switching the derivatives (force switch).
DerivativePair operator()(double score, double deriv, double distance) const
Smooth the score and its first derivative at a given distance.