IMP  2.4.0
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-2015 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  double evaluate_if_good(bool calc_derivatives) const;
74 
75  //! \see Model::evaluate_with_maximum()
76  double evaluate_if_below(bool calc_derivatives, double max) const;
77 
78  /** \name Evaluation implementation
79  These methods are called in order to perform the actual restraint
80  scoring. The restraints should assume that all appropriate ScoreState
81  objects have been updated and so that the input particles and containers
82  are up to date. The returned score should be the unweighted score.
83 
84  \note These functions probably should be called \c do_evaluate, but
85  were grandfathered in.
86  \note Although the returned score is unweighted, the DerivativeAccumulator
87  passed in had better be properly weighted.
88  @{
89  */
90  //! Return the unweighted score for the restraint.
91  virtual double unprotected_evaluate(DerivativeAccumulator *da) const;
92  /** The function calling this will treat any score >= get_maximum_score
93  as bad and so can return early as soon as such a situation is found.*/
94  virtual double unprotected_evaluate_if_good(DerivativeAccumulator *da,
95  double max) const {
96  IMP_UNUSED(max);
97  return unprotected_evaluate(da);
98  }
99 
100  //! The function calling this will treat any score >= max as bad.
101  virtual double unprotected_evaluate_if_below(DerivativeAccumulator *da,
102  double max) const {
103  IMP_UNUSED(max);
104  return unprotected_evaluate(da);
105  }
106 /** @} */
107 #endif
108 
109  //! Perform the actual restraint scoring.
110  /** The restraints should assume that all appropriate ScoreState
111  objects have been updated and so that the input particles and containers
112  are up to date. The returned score should be the unweighted score.
113  */
114  void add_score_and_derivatives(ScoreAccumulator sa) const;
115 
116  //! Decompose this restraint into constituent terms
117  /** Given the set of input particles, decompose the restraint into parts
118  that are as simple as possible. For many restraints, the simplest
119  part is simply the restraint itself.
120 
121  If a restraint can be decomposed, it should return a
122  RestraintSet so that the maximum score and weight can be
123  passed properly.
124 
125  The restraints returned have had set_model() called and so can
126  be evaluated.
127  */
129 
130  //! Decompose this restraint into constituent terms for the current conf
131  /** \return a decomposition that is value for the current conformation,
132  but will not necessarily be valid if any of the particles are
133  changed. This is the same as create_decomposition() for
134  non-conditional restraints.
135 
136  The restraints returned have had set_model() called and so can be
137  evaluated.
138  */
139  Restraint *create_current_decomposition() const;
140 
141  /** \name Weights
142  Each restraint's contribution to the model score is weighted. The
143  total weight for the restraint is the some over all the paths containing
144  it. That is, if a restraint is in a RestraintSet with weight .5 and
145  another with weight 2, and the restaint itself has weight 3, then the
146  total weight of the restraint is \f$.5 \cdot 3 + 2 \cdot 3 = 7.5 \f$.
147  @{
148  */
149  void set_weight(Float weight);
150  Float get_weight() const { return weight_; }
151  /** @} */
152  /** \name Filtering
153  We are typically only interested in "good" conformations of
154  the model. These are described by specifying maximum scores
155  per restraint and for the whole model. Samplers, optimizers
156  etc are free to ignore configurations they encounter which
157  go outside these bounds.
158 
159  \note The maximum score is for the unweighted restraint.
160  That is, the restraint evaluation is bad if the value
161  is greater than the maximum score divided by the weight.
162  @{
163  */
164  double get_maximum_score() const { return max_; }
165  void set_maximum_score(double s);
166 /** @} */
167 
168 //! Create a scoring function with only this restraint.
169 /** \note This method cannot be implemented in Python due to memory
170  management issues (and the question of why you would ever
171  want to).
172  */
173 #ifndef SWIG
174  virtual
175 #endif
177  create_scoring_function(double weight = 1.0,
178  double max = NO_MAX) const;
179 #if !defined(IMP_DOXYGEN)
180  void set_last_score(double s) const { last_score_ = s; }
181 #endif
182 
183  /** Return the (unweighted) score for this restraint last time it was
184  evaluated.
185  \note If some sort of special evaluation (eg Model::evaluate_if_good())
186  was the last call, the score, if larger than the max, is not accurate.
187  */
188  virtual double get_last_score() const { return last_score_; }
189  /** Return whether this restraint violated its maximum last time it was
190  evaluated.
191  */
192  bool get_was_good() const { return get_last_score() < max_; }
193 
195 
196  protected:
197  /** A Restraint should override this if they want to decompose themselves
198  for domino and other purposes. The returned restraints will be made
199  in to a RestraintSet, if needed and the weight and maximum score
200  set for the restraint set.
201  */
203  return Restraints(1, const_cast<Restraint *>(this));
204  }
205  /** A Restraint should override this if they want to decompose themselves
206  for display and other purposes. The returned restraints will be made
207  in to a RestraintSet, if needed and the weight and maximum score
208  set for the restraint set.
209 
210  The returned restraints should be only the non-zero terms and should
211  have their last scores set appropriately;
212  */
214  return do_create_decomposition();
215  }
216  /** A restraint should override this to compute the score and derivatives.
217  */
218  virtual void do_add_score_and_derivatives(ScoreAccumulator sa) const;
219 
220  /** No outputs. */
222 
223  private:
224  ScoringFunction *create_internal_scoring_function() const;
225 
226  double weight_;
227  double max_;
228  mutable double last_score_;
229  // cannot be released outside the class
230  mutable base::Pointer<ScoringFunction> cached_internal_scoring_function_;
231 };
232 
233 /** This class is to provide a consisted interface for things
234  that take Restraints as arguments.
235 
236  \note Passing an empty list of restraints should be supported, but problems
237  could arise, so be alert (the problems would not be subtle).
238 */
239 class IMPKERNELEXPORT RestraintsAdaptor :
240 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
241  public Restraints
242 #else
243  public base::InputAdaptor
244 #endif
245  {
246  static Restraint *get(kernel::Model *sf);
247  static Restraint *get(Restraint *r) { return r; }
248 
249  public:
250  RestraintsAdaptor() {}
251  RestraintsAdaptor(const Restraints &sf) : Restraints(sf) {}
253  : Restraints(sf.begin(), sf.end()) {}
254  RestraintsAdaptor(Restraint *sf) : Restraints(1, sf) {}
255 #ifndef IMP_DOXYGEN
257  RestraintsAdaptor(const ModelsTemp &sf);
258  template <class T>
259  RestraintsAdaptor(base::internal::PointerBase<T> t)
260  : Restraints(1, get(t)) {}
261 #endif
262 };
263 
264 //! Return the decomposition of a list of restraints.
265 IMPKERNELEXPORT Restraints create_decomposition(const RestraintsTemp &rs);
266 
267 IMPKERNEL_END_NAMESPACE
268 
269 #endif /* IMPKERNEL_RESTRAINT_H */
Restraints create_decomposition(const RestraintsTemp &rs)
Return the decomposition of a list of restraints.
Class for adding derivatives from restraints to the model.
Control display of deprecation information.
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.
IMP::base::Vector< IMP::base::Pointer< Restraint > > Restraints
A smart pointer to a reference counted object.
Definition: Pointer.h:87
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
Represents a scoring function on the model.
ScoringFunction * create_scoring_function(RestraintType *rs, double weight=1.0, double max=NO_MAX, std::string name=std::string())
Class for adding scores from restraints to the model.
Basic types used by IMP.
virtual double get_last_score() const
Single variable function.
#define IMP_UNUSED(variable)
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: 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:73