IMP  2.2.1
The Integrative Modeling Platform
kernel/Restraint.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/Restraint.h
3  * \brief Abstract base class for all restraints.
4  *
5  * Copyright 2007-2014 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPKERNEL_RESTRAINT_H
10 #define IMPKERNEL_RESTRAINT_H
11 
12 #include <IMP/kernel/kernel_config.h>
13 #include "ModelObject.h"
14 #include "ScoreAccumulator.h"
15 #include "DerivativeAccumulator.h"
16 #include "constants.h"
17 #include "base_types.h"
18 #include <IMP/base/InputAdaptor.h>
20 
21 IMPKERNEL_BEGIN_NAMESPACE
23 
24 //! A restraint is a term in an \imp ScoringFunction.
25 /**
26  To implement a new restraint, just implement the two methods:
27  - IMP::Restraint::do_add_score_and_derivatives()
28  - IMP::ModelObject::do_get_inputs();
29  and use the macro to handle IMP::base::Object
30  - IMP_OBJECT_METHODS()
31 
32  \note When logging is VERBOSE, restraints should print enough information
33  in evaluate to reproduce the the entire flow of data in evaluate. When
34  logging is TERSE the restraint should print out only a constant number of
35  lines per evaluate call.
36 
37  \note Physical restraints should use the units of kcal/mol for restraint
38  values and kcal/mol/A for derivatives.
39 
40  When implementing an expensive restraint it makes sense to support early
41  abort of evaluation if the user is only interested in good scores or scores
42  below a threshold. To do this, look at the fields of the ScoreAccumulator
43  object such as
44  - ScoreAccumulator::get_is_evaluate_if_below(),
45  - ScoreAccumulator::get_is_evaluate_if_good()
46  - ScoreAccumulator::get_maximum()
47 
48  \headerfile Restraint.h "IMP/Restraint.h"
49 
50  See IMP::example::ExampleRestraint for an example.
51  */
52 class IMPKERNELEXPORT Restraint : public ModelObject {
53  public:
54  /** Create a restraint and register it with the model. The restraint is
55  not added to the implicit scoring function in the Model.*/
56  Restraint(kernel::Model *m, std::string name);
57 
58  /** Compute and return the current score for the restraint.
59  */
60  double get_score() const;
61 
62 #ifndef IMP_DOXYGEN
63  //! Return the score for this restraint for the current state of the model.
64  /** \return Current score.
65 
66  This method is equivalent to calling:
67  \code
68  model->evaluate(RestraintsTemp(1,this), calc_derivs)
69  \endcode
70  */
71  double evaluate(bool calc_derivs) const;
72 
73  //! See Model::evaluate_if_good()
74  double evaluate_if_good(bool calc_derivatives) const;
75 
76  //! See Model::evaluate_with_maximum()
77  double evaluate_if_below(bool calc_derivatives, double max) const;
78 
79  /** \name Evaluation implementation
80  These methods are called in order to perform the actual restraint
81  scoring. The restraints should assume that all appropriate ScoreState
82  objects have been updated and so that the input particles and containers
83  are up to date. The returned score should be the unweighted score.
84 
85  \note These functions probably should be called \c do_evaluate, but
86  were grandfathered in.
87  \note Although the returned score is unweighted, the DerivativeAccumulator
88  passed in had better be properly weighted.
89  @{
90  */
91  /** Return the unweighted score for the restraint.*/
92  virtual double unprotected_evaluate(DerivativeAccumulator *da) const;
93  /** The function calling this will treat any score >= get_maximum_score
94  as bad and so can return early as soon as such a situation is found.*/
95  virtual double unprotected_evaluate_if_good(DerivativeAccumulator *da,
96  double max) const {
97  IMP_UNUSED(max);
98  return unprotected_evaluate(da);
99  }
100 
101  /** The function calling this will treat any score >= max as bad.*/
102  virtual double unprotected_evaluate_if_below(DerivativeAccumulator *da,
103  double max) const {
104  IMP_UNUSED(max);
105  return unprotected_evaluate(da);
106  }
107 /** @} */
108 #endif
109 
110  /** This methid is called in order to perform the actual restraint
111  scoring. The restraints should assume that all appropriate ScoreState
112  objects have been updated and so that the input particles and containers
113  are up to date. The returned score should be the unweighted score.
114  */
115  void add_score_and_derivatives(ScoreAccumulator sa) const;
116 
117  //! Decompose this restraint into constituent terms
118  /** Given the set of input particles, decompose the restraint into as
119  simple parts as possible. For many restraints, the simplest
120  part is simply the restraint itself.
121 
122  If a restraint can be decomposed, it should return a
123  RestraintSet so that the maximum score and weight can be
124  passed properly.
125 
126  The restraints returned have had set_model() called and so can
127  be evaluated.
128  */
130 
131  //! Decompose this restraint into constituent terms for the current conf
132  /** Return a decomposition that is value for the current conformation,
133  but will not necessarily be valid if any of the particles are
134  changed. This is the same as create_decomposition() for
135  non-conditional restraints.
136 
137  The restraints returned have had set_model() called and so can be
138  evaluated.
139  */
140  Restraint *create_current_decomposition() const;
141 
142  /** \name Weights
143  Each restraint's contribution to the model score is weighted. The
144  total weight for the restraint is the some over all the paths containing
145  it. That is, if a restraint is in a RestraintSet with weight .5 and
146  another with weight 2, and the restaint itself has weight 3, then the
147  total weight of the restraint is \f$.5 \cdot 3 + 2 \cdot 3 = 7.5 \f$.
148  @{
149  */
150  void set_weight(Float weight);
151  Float get_weight() const { return weight_; }
152  /** @} */
153  /** \name Filtering
154  We are typically only interested in "good" conformations of
155  the model. These are described by specifying maximum scores
156  per restraint and for the whole model. Samplers, optimizers
157  etc are free to ignore configurations they encounter which
158  go outside these bounds.
159 
160  \note The maximum score is for the unweighted restraint.
161  That is, the restraint evaluation is bad if the value
162  is greater than the maximum score divided by the weight.
163  @{
164  */
165  double get_maximum_score() const { return max_; }
166  void set_maximum_score(double s);
167 /** @} */
168 
169 /** Create a scoring function with only this restarint.
170 
171  \note This method cannot be implemented in python due to memory
172  management issues (and the question of why you would ever
173  want to).
174  */
175 #ifndef SWIG
176  virtual
177 #endif
179  create_scoring_function(double weight = 1.0,
180  double max = NO_MAX) const;
181 #if !defined(IMP_DOXYGEN)
182  void set_last_score(double s) const { last_score_ = s; }
183 #endif
184 
185  /** Return the (unweighted) score for this restraint last time it was
186  evaluated.
187  \note If some sort of special evaluation (eg Model::evaluate_if_good())
188  was the last call, the score, if larger than the max, is not accurate.
189  */
190  virtual double get_last_score() const { return last_score_; }
191  /** Return whether this restraint violated it maximum last time it was
192  evaluated.
193  */
194  bool get_was_good() const { return get_last_score() < max_; }
195 
197 
198  protected:
199  /** A Restraint should override this if they want to decompose themselves
200  for domino and other purposes. The returned restraints will be made
201  in to a RestraintSet, if needed and the weight and maximum score
202  set for the restraint set.
203  */
205  return Restraints(1, const_cast<Restraint *>(this));
206  }
207  /** A Restraint should override this if they want to decompose themselves
208  for display and other purposes. The returned restraints will be made
209  in to a RestraintSet, if needed and the weight and maximum score
210  set for the restraint set.
211 
212  The returned restraints should be only the non-zero terms and should
213  have their last scores set appropriately;
214  */
216  return do_create_decomposition();
217  }
218  /** A restraint should override this to compute the score and derivatives.
219  */
220  virtual void do_add_score_and_derivatives(ScoreAccumulator sa) const;
221 
222  /** No outputs. */
224 
225  private:
226  ScoringFunction *create_internal_scoring_function() const;
227 
228  double weight_;
229  double max_;
230  mutable double last_score_;
231  // cannot be released outside the class
232  mutable base::Pointer<ScoringFunction> cached_internal_scoring_function_;
233 };
234 
235 /** This class is to provide a consisted interface for things
236  that take Restraints as arguments.
237 
238  \note Passing an empty list of restraints should be supported, but problems
239  could arise, so be alert (the problems would not be subtle).
240 */
241 class IMPKERNELEXPORT RestraintsAdaptor :
242 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
243  public Restraints
244 #else
245  public base::InputAdaptor
246 #endif
247  {
248  static Restraint *get(kernel::Model *sf);
249  static Restraint *get(Restraint *r) { return r; }
250 
251  public:
252  RestraintsAdaptor() {}
253  RestraintsAdaptor(const Restraints &sf) : Restraints(sf) {}
255  : Restraints(sf.begin(), sf.end()) {}
256  RestraintsAdaptor(Restraint *sf) : Restraints(1, sf) {}
257 #ifndef IMP_DOXYGEN
259  RestraintsAdaptor(const ModelsTemp &sf);
260  template <class T>
261  RestraintsAdaptor(base::internal::PointerBase<T> t)
262  : Restraints(1, get(t)) {}
263 #endif
264 };
265 
266 /** Return the decomposition of a list of restraints. */
267 IMPKERNELEXPORT Restraints create_decomposition(const RestraintsTemp &rs);
268 
269 IMPKERNEL_END_NAMESPACE
270 
271 #endif /* IMPKERNEL_RESTRAINT_H */
Restraints create_decomposition(const RestraintsTemp &rs)
Class for adding derivatives from restraints to the model.
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
Class for adding derivatives from restraints to the model.
IMP::base::Vector< IMP::base::WeakPointer< kernel::ModelObject > > ModelObjectsTemp
IMP::kernel::DerivativeAccumulator DerivativeAccumulator
Basic types used by IMP.
#define IMP_UNUSED(variable)
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
IMP::base::Vector< IMP::base::Pointer< Restraint > > Restraints
A smart pointer to a reference counted object.
Definition: base/Pointer.h:87
ScoringFunction * create_scoring_function(RestraintType *rs, double weight=1.0, double max=NO_MAX, std::string name=std::string())
Control display of deprecation information.
Class for adding scores from restraints to the model.
virtual double get_last_score() const
Single variable function.
Basic types used by IMP.
Class for adding up scores during ScoringFunction evaluation.
A restraint is a term in an IMP ScoringFunction.
ModelObjectsTemp do_get_outputs() const
virtual Restraints do_create_current_decomposition() const
double Float
Basic floating-point value (could be float, double...)
Definition: base/types.h:20
virtual Restraints do_create_decomposition() const
IMP::kernel::Restraint Restraint
Various useful constants.
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:72