IMP logo
IMP Reference Guide  2.20.0
The Integrative Modeling Platform
SurfaceTetheredChain.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/SurfaceTetheredChain.h
3  * \brief Score on surface-to-end distance of chain tethered to impenetrable surface
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPCORE_SURFACE_TETHERED_CHAIN_H
9 #define IMPCORE_SURFACE_TETHERED_CHAIN_H
10 
11 #include <IMP/core/core_config.h>
12 #include <IMP/UnaryFunction.h>
13 #include <IMP/constants.h>
14 
15 IMPCORE_BEGIN_NAMESPACE
16 
17 //! Score on surface-to-end distance of chain tethered to impenetrable surface
18 /** When a flexible linker is represented by the freely jointed chain model with
19  one end tethered to an impenetrable surface, the distance \f$ z \f$ of the
20  free end from the surface follows the distribution
21  \f[ p(z | \beta) = 2 \beta z \exp{(-\beta z^2)}, \f]
22  where \f$ \beta = \frac{3}{2 N b^2} \f$, \f$ N \f$ is the number of links,
23  and \f$ b \f$ is the average length of a single link. The score reaches its
24  minimum value when \f$ z = \frac{1}{\sqrt{2 \beta}} \f$.
25 
26  See KA Dill, S Bromberg. Molecular Driving Forces. 2nd Edition. 2010.
27  Eq 34.7.
28 
29  \note While the Gaussian approximation breaks down when \f$z > N b\f$, the
30  score naturally increases as a harmonic restraint with force constant
31  \f$2 \beta\f$.
32 
33  \note The resulting score blows up as the \f$ z \f$ approaches 0.
34  Therefore, in this implementation, when \f$ z = .01 z_{min} \f$, where
35  \f$ z_{min} \f$ is the value of \f$ z \f$ where the score is minimized,
36  then the score increases linearly as \f$ z \f$ decreases.
37 
38  \see misc::FreelyJointedChain
39  \see misc::WormLikeChain
40  \see Harmonic
41  \see SurfaceHeightPairScore
42 */
44 
45  private:
46  void initialize() {
47  double N = (double) N_;
48  beta_ = 3. / 2. / N / b_ / b_;
49  z_min_ = 0.01 / sqrt(2 * beta_);
50  z_min_deriv_ = -141.4072141 * sqrt(beta_);
51  z_min_int_ = 5.2585466 - std::log(beta_) / 2.;
52  }
53 
54  public:
55  SurfaceTetheredChain(int link_num, double link_length)
56  : N_(link_num), b_(link_length) {
57  IMP_USAGE_CHECK(N_ > 0, "Number of links must be positive.");
58  IMP_USAGE_CHECK(b_ > 0, "Link length must be positive.");
59  initialize();
60  }
61 
63  double feature) const override {
64  if (feature < z_min_) {
65  return DerivativePair(z_min_deriv_ * feature + z_min_int_,
66  z_min_deriv_);
67  } else {
68  return DerivativePair(beta_ * feature * feature -
69  std::log(2 * beta_ * feature),
70  2. * beta_ * feature - 1. / feature);
71  }
72  }
73 
74  virtual double evaluate(double feature) const override {
75  return evaluate_with_derivative(feature).first;
76  }
77 
79 
80  //! Get number of links in chain.
81  int get_link_number() const { return N_; }
82 
83  //! Get length of each chain link.
84  double get_link_length() const { return b_; }
85 
86  //! Set the number of links in chain.
87  void set_link_number(int N) {
88  N_ = N;
89  IMP_USAGE_CHECK(N_ > 0, "Number of links must be positive.");
90  initialize();
91  }
92 
93  //! Set the length of each chain link.
94  void set_link_length(double b) {
95  b_ = b;
96  IMP_USAGE_CHECK(b_ > 0, "Link length must be positive.");
97  initialize();
98  }
99 
100  //! Get the distance at which the score is at its minimum value.
101  double get_distance_at_minimum() const {
102  return 1. / sqrt(2 * beta_);
103  }
104 
105  //! Get the average distance from the surface.
106  double get_average_distance() const {
107  return sqrt(PI / beta_) / 2.;
108  }
109 
110  private:
111  int N_;
112  double b_;
113  double beta_, z_min_, z_min_deriv_, z_min_int_;
114 };
115 
116 IMPCORE_END_NAMESPACE
117 
118 #endif /* IMPCORE_SURFACE_TETHERED_CHAIN_H */
double get_link_length() const
Get length of each chain link.
static const double PI
the constant pi
virtual double evaluate(double feature) const override
Calculate score with respect to the given feature.
Various useful constants.
double get_distance_at_minimum() const
Get the distance at which the score is at its minimum value.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Single variable function.
Score on surface-to-end distance of chain tethered to impenetrable surface.
int get_link_number() const
Get number of links in chain.
void set_link_number(int N)
Set the number of links in chain.
std::pair< double, double > DerivativePair
A pair representing a function value with its first derivative.
Definition: types.h:22
void set_link_length(double b)
Set the length of each chain link.
double get_average_distance() const
Get the average distance from the surface.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
virtual DerivativePair evaluate_with_derivative(double feature) const override
Calculate score and derivative with respect to the given feature.
Abstract single variable functor class for score functions.
Definition: UnaryFunction.h:27