IMP logo
IMP Reference Guide  2.20.1
The Integrative Modeling Platform
TruncatedHarmonic.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/TruncatedHarmonic.h \brief Truncated harmonic.
3  *
4  * Copyright 2007-2022 IMP Inventors. All rights reserved.
5  */
6 
7 #ifndef IMPCORE_TRUNCATED_HARMONIC_H
8 #define IMPCORE_TRUNCATED_HARMONIC_H
9 
10 #include <IMP/core/core_config.h>
11 #include "internal/truncated_harmonic.h"
12 #include <IMP/UnaryFunction.h>
13 #include <IMP/object_macros.h>
14 #include <IMP/utility.h>
15 
16 IMPCORE_BEGIN_NAMESPACE
17 
18 enum BoundDirection {
19  LOWER,
20  BOTH,
21  UPPER
22 };
23 
24 //! A function that is harmonic over an bounded interval.
25 /** This is a harmonic function of the form
26  $f(x) = 0.5 \cdot k \cdot (x-center)^2$ within a bounded interval
27  around a center value, in the bounded interval where $\|x-center\|<threshold$,
28  i.e. up to a threshold offset from the center. Beyond the threshold offset,
29  the function asymptotically converges to the limit value.
30 
31  \param[in] DIRECTION This template parameter determines whether the function
32  is non-zero only for input values that are greater than the center (UPPER),
33  lower than the center (LOWER), or both (BOTH). In Python code, these choices
34  can be specified using the types TruncatedHarmonicUpperBound,
35  TruncatedHarmonicLowerBound, and TruncatedHarmonic, respectively.
36 
37  For example, if the center equals to 5, the threshold to 2, and the direction
38  is BOTH (see below), then the function is harmonic in the interval [3,7],
39  and beyond that interval it converges to the limit value in either direction.
40  If the direction is LOWER, then the function is harmonic in the interval
41  [3,5], it converges to the limit value for values lower thans 3, and is 0
42  for values higher than 5. If it is UPPER, then the function is harmonic in
43  the interval [5,7], it is 0 for values lower than 5, and it converges to
44  the limit value for values higher than 7.
45 
46  @note The function form beyond the threshold offset from center is currently
47  limit-b/(x-o) where x is the offset from the center and b,o are constants
48  chosen to make the function smooth and continuous. This form may change
49  without notice unless someone tells us it is important that it does
50  not.
51 
52  \see Harmonic
53  \see HarmonicLowerBound
54  \see HarmonicUpperBound
55  */
56 template <int DIRECTION>
58  public:
59  /** \param[in] center The center point for the truncated harmonic.
60  \param[in] k The spring constant for the truncated harmonic.
61  \param[in] threshold How far the harmonic term extends from the center.
62  \param[in] limit The value to which the function converges above the
63  threshold.
64 
65  \note I don't like having 4 floats on the initializer list, but
66  don't really see an alternative. There are a few sanity checks, so
67  the order is a bit hard to get wrong.
68  */
69  TruncatedHarmonic(Float center, Float k, Float threshold, Float limit)
70  : d_(center, k, threshold, limit) {}
71  /** Same as other constructor, but automatically set limit to a reasonable default value. */
72  TruncatedHarmonic(Float center, Float k, Float threshold)
73  : d_(center, k, threshold, k * square(threshold)) {}
74  virtual DerivativePair evaluate_with_derivative(double feature) const
75  override {
76  return DerivativePair(evaluate(feature),
77  ((DIRECTION == LOWER && (feature > d_.c_)) ||
78  (DIRECTION == UPPER && (feature < d_.c_)))
79  ? 0
80  : d_.evaluate_with_derivative(feature).second);
81  }
82  virtual double evaluate(double feature) const override {
83  return ((DIRECTION == LOWER && (feature > d_.c_)) ||
84  (DIRECTION == UPPER && (feature < d_.c_)))
85  ? 0
86  : d_.evaluate(feature);
87  }
89 
90  private:
91  internal::TruncatedHarmonicData d_;
92 };
93 
94 //! A specialization of TruncatedHarmonic that returns a non-zero value
95 //! only for input values that are greater than the center value
97 
98 //! A specialization of TruncatedHarmonic that returns a non-zero value
99 //! only for input values that are lower than the center value
101 
102 //! A specialization of TruncatedHarmonic that returns non-zero value
103 //! for any input values other than center value
105 
106 IMPCORE_END_NAMESPACE
107 
108 #endif /* IMPCORE_TRUNCATED_HARMONIC_H */
Helper macros for implementing IMP Objects.
A function that is harmonic over an bounded interval.
TruncatedHarmonic(Float center, Float k, Float threshold, Float limit)
TruncatedHarmonic(Float center, Float k, Float threshold)
virtual double evaluate(double feature) const override
Calculate score with respect to the given feature.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Single variable function.
virtual DerivativePair evaluate_with_derivative(double feature) const override
Calculate score and derivative with respect to the given feature.
Various general useful functions for IMP.
std::pair< double, double > DerivativePair
A pair representing a function value with its first derivative.
Definition: types.h:22
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:19
TruncatedHarmonic< BOTH > TruncatedHarmonicBound
TruncatedHarmonic< UPPER > TruncatedHarmonicUpperBound
Abstract single variable functor class for score functions.
Definition: UnaryFunction.h:27
TruncatedHarmonic< LOWER > TruncatedHarmonicLowerBound