IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
FreelyJointedChain.h
Go to the documentation of this file.
1 /**
2  * \file IMP/misc/FreelyJointedChain.h
3  * \brief Score on end-to-end distance of freely jointed chain
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPMISC_FREELY_JOINTED_CHAIN_H
9 #define IMPMISC_FREELY_JOINTED_CHAIN_H
10 
11 #include <IMP/misc/misc_config.h>
12 #include <IMP/UnaryFunction.h>
13 #include <IMP/constants.h>
14 
15 IMPMISC_BEGIN_NAMESPACE
16 
17 //! Score on end-to-end distance of freely jointed chain
18 /** A flexible linker can be represented by the freely jointed chain model as a
19  polymer under a Gaussian random walk. The end-to-end distance \f$ z \f$ then
20  follows the distribution
21  \f[p(z | \beta) = 4 \pi z^2 (\frac{\beta}{\pi})^{3/2)} \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{\beta}} \f$.
25 
26  See KA Dill, S Bromberg. Molecular Driving Forces. 2nd Edition. 2010.
27  Eqs 33.26, 33.27.
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 WormLikeChain
39  \see core::Harmonic
40 */
42 
43  private:
44  void initialize() {
45  double N = (double) N_;
46  beta_ = 3. / 2. / N / b_ / b_;
47  z_min_ = 0.01 / sqrt(beta_);
48  z_min_deriv_ = -199.98 * sqrt(beta_);
49  z_min_int_ = 10.39631095 - std::log(beta_) / 2.;
50  }
51 
52  public:
53  FreelyJointedChain(int link_num, double link_length)
54  : N_(link_num), b_(link_length) {
55  IMP_USAGE_CHECK(N_ > 0, "Number of links must be positive.");
56  IMP_USAGE_CHECK(b_ > 0, "Link length must be positive.");
57  initialize();
58  }
59 
60  virtual DerivativePair evaluate_with_derivative(double feature) const {
61  if (feature < 0) feature = 0;
62  if (feature < z_min_) {
63  return DerivativePair(z_min_deriv_ * feature + z_min_int_,
64  z_min_deriv_);
65  } else {
66  return DerivativePair(beta_ * feature * feature -
67  2 * std::log(2 * feature) +
68  std::log(PI / std::pow(beta_, 3)) / 2.,
69  2. * beta_ * feature - 2.0 / feature);
70  }
71  }
72 
73  virtual double evaluate(double feature) const {
74  return evaluate_with_derivative(feature).first;
75  }
76 
78 
79  //! Get number of links in chain.
80  int get_link_number() const { return N_; }
81 
82  //! Get length of each chain link.
83  double get_link_length() const { return b_; }
84 
85  //! Set the number of links in chain.
86  void set_link_number(int N) {
87  N_ = N;
88  IMP_USAGE_CHECK(N_ > 0, "Number of links must be positive.");
89  initialize();
90  }
91 
92  //! Set the length of each chain link.
93  void set_link_length(double b) {
94  b_ = b;
95  IMP_USAGE_CHECK(b_ > 0, "Link length must be positive.");
96  initialize();
97  }
98 
99  //! Get the distance at which the score is at its minimum value.
100  double get_distance_at_minimum() const {
101  return 1. / sqrt(beta_);
102  }
103 
104  //! Get the average distance from the surface.
105  double get_average_distance() const {
106  return 2. / sqrt(PI * beta_);
107  }
108 
109  private:
110  int N_;
111  double b_;
112  double beta_, z_min_, z_min_deriv_, z_min_int_;
113 };
114 
115 IMPMISC_END_NAMESPACE
116 
117 #endif /* IMPMISC_FREELY_JOINTED_CHAIN_H */
double get_average_distance() const
Get the average distance from the surface.
static const double PI
the constant pi
Various useful constants.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Score on end-to-end distance of freely jointed chain.
Single variable function.
void set_link_length(double b)
Set the length of each chain link.
double get_distance_at_minimum() const
Get the distance at which the score is at its minimum value.
double get_link_length() const
Get length of each chain link.
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
virtual DerivativePair evaluate_with_derivative(double feature) const
Calculate score and derivative with respect to the given feature.
int get_link_number() const
Get number of links in chain.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
virtual double evaluate(double feature) const
Calculate score with respect to the given feature.
Abstract single variable functor class for score functions.
Definition: UnaryFunction.h:27