IMP  2.1.0
The Integrative Modeling Platform
kernel/declare_Restraint.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/declare_Restraint.h
3  * \brief Abstract base class for all restraints.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPKERNEL_DECLARE_RESTRAINT_H
10 #define IMPKERNEL_DECLARE_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  /** \deprecated_at{2.1} Use the constructor that takes a model instead.
58  */
59  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
60  Restraint(std::string name = "Restraint %1%");
61 
62  /** Compute and return the current score for the restraint.
63  */
64  double get_score() const;
65 
66 #ifndef IMP_DOXYGEN
67  //! Return the score for this restraint for the current state of the model.
68  /** \return Current score.
69 
70  This method is equivalent to calling:
71  \code
72  model->evaluate(RestraintsTemp(1,this), calc_derivs)
73  \endcode
74  */
75  double evaluate(bool calc_derivs) const;
76 
77  //! See Model::evaluate_if_good()
78  double evaluate_if_good(bool calc_derivatives) const;
79 
80  //! See Model::evaluate_with_maximum()
81  double evaluate_if_below(bool calc_derivatives, double max) const;
82 
83  /** \name Evaluation implementation
84  These methods are called in order to perform the actual restraint
85  scoring. The restraints should assume that all appropriate ScoreState
86  objects have been updated and so that the input particles and containers
87  are up to date. The returned score should be the unweighted score.
88 
89  \note These functions probably should be called \c do_evaluate, but
90  were grandfathered in.
91  \note Although the returned score is unweighted, the DerivativeAccumulator
92  passed in had better be properly weighted.
93  @{
94  */
95  /** Return the unweighted score for the restraint.*/
96  virtual double unprotected_evaluate(DerivativeAccumulator *da) const;
97  /** The function calling this will treat any score >= get_maximum_score
98  as bad and so can return early as soon as such a situation is found.*/
99  virtual double unprotected_evaluate_if_good(DerivativeAccumulator *da,
100  double max) const {
101  IMP_UNUSED(max);
102  return unprotected_evaluate(da);
103  }
104 
105  /** The function calling this will treat any score >= max as bad.*/
106  virtual double unprotected_evaluate_if_below(DerivativeAccumulator *da,
107  double max) const {
108  IMP_UNUSED(max);
109  return unprotected_evaluate(da);
110  }
111 /** @} */
112 #endif
113 
114  /** This methid is called in order to perform the actual restraint
115  scoring. The restraints should assume that all appropriate ScoreState
116  objects have been updated and so that the input particles and containers
117  are up to date. The returned score should be the unweighted score.
118  */
119  void add_score_and_derivatives(ScoreAccumulator sa) const;
120 
121  //! Decompose this restraint into constituent terms
122  /** Given the set of input particles, decompose the restraint into as
123  simple parts as possible. For many restraints, the simplest
124  part is simply the restraint itself.
125 
126  If a restraint can be decomposed, it should return a
127  RestraintSet so that the maximum score and weight can be
128  passed properly.
129 
130  The restraints returned have had set_model() called and so can
131  be evaluated.
132  */
134 
135  //! Decompose this restraint into constituent terms for the current conf
136  /** Return a decomposition that is value for the current conformation,
137  but will not necessarily be valid if any of the particles are
138  changed. This is the same as create_decomposition() for
139  non-conditional restraints.
140 
141  The restraints returned have had set_model() called and so can be
142  evaluated.
143  */
144  Restraint *create_current_decomposition() const;
145 
146  /** \name Weights
147  Each restraint's contribution to the model score is weighted. The
148  total weight for the restraint is the some over all the paths containing
149  it. That is, if a restraint is in a RestraintSet with weight .5 and
150  another with weight 2, and the restaint itself has weight 3, then the
151  total weight of the restraint is \f$.5 \cdot 3 + 2 \cdot 3 = 7.5 \f$.
152  @{
153  */
154  void set_weight(Float weight);
155  Float get_weight() const { return weight_; }
156  /** @} */
157  /** \name Filtering
158  We are typically only interested in "good" conformations of
159  the model. These are described by specifying maximum scores
160  per restraint and for the whole model. Samplers, optimizers
161  etc are free to ignore configurations they encounter which
162  go outside these bounds.
163 
164  \note The maximum score is for the unweighted restraint.
165  That is, the restraint evaluation is bad if the value
166  is greater than the maximum score divided by the weight.
167  @{
168  */
169  double get_maximum_score() const { return max_; }
170  void set_maximum_score(double s);
171 /** @} */
172 
173 /** Create a scoring function with only this restarint.
174 
175  \note This method cannot be implemented in python due to memory
176  management issues (and the question of why you would ever
177  want to).
178  */
179 #ifndef SWIG
180  virtual
181 #endif
183  create_scoring_function(double weight = 1.0,
184  double max = NO_MAX) const;
185 #if !defined(IMP_DOXYGEN)
186  void set_last_score(double s) const { last_score_ = s; }
187 #endif
188 
189  /** Return the (unweighted) score for this restraint last time it was
190  evaluated.
191  \note If some sort of special evaluation (eg Model::evaluate_if_good())
192  was the last call, the score, if larger than the max, is not accurate.
193  */
194  virtual double get_last_score() const { return last_score_; }
195  /** Return whether this restraint violated it maximum last time it was
196  evaluated.
197  */
198  bool get_was_good() const { return get_last_score() < max_; }
199 
200  /** \deprecated_at{2.1} use get_inputs() instead.*/
201  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
203  /** \deprecated_at{2.1} use get_inputs() instead.*/
204  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
206 
208 
209  protected:
210  /** A Restraint should override this if they want to decompose themselves
211  for domino and other purposes. The returned restraints will be made
212  in to a RestraintSet, if needed and the weight and maximum score
213  set for the restraint set.
214  */
215  virtual Restraints do_create_decomposition() const {
216  return Restraints(1, const_cast<Restraint *>(this));
217  }
218  /** A Restraint should override this if they want to decompose themselves
219  for display and other purposes. The returned restraints will be made
220  in to a RestraintSet, if needed and the weight and maximum score
221  set for the restraint set.
222 
223  The returned restraints should be only the non-zero terms and should
224  have their last scores set appropriately;
225  */
227  return do_create_decomposition();
228  }
229  /** A restraint should override this to compute the score and derivatives.
230  */
231  virtual void do_add_score_and_derivatives(ScoreAccumulator sa) const;
232 
233  /** No outputs. */
235 
236  private:
237  ScoringFunction *create_internal_scoring_function() const;
238 
239  double weight_;
240  double max_;
241  mutable double last_score_;
242  // cannot be released outside the class
243  mutable base::Pointer<ScoringFunction> cached_internal_scoring_function_;
244 };
245 
246 /** This class is to provide a consisted interface for things
247  that take Restraints as arguments.
248 
249  \note Passing an empty list of restraints should be supported, but problems
250  could arise, so be alert (the problems would not be subtle).
251 */
252 class IMPKERNELEXPORT RestraintsAdaptor :
253 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
254  public Restraints
255 #else
256  public base::InputAdaptor
257 #endif
258  {
259  static Restraint *get(kernel::Model *sf);
260  static Restraint *get(Restraint *r) { return r; }
261 
262  public:
263  RestraintsAdaptor() {}
264  RestraintsAdaptor(const Restraints &sf) : Restraints(sf) {}
266  : Restraints(sf.begin(), sf.end()) {}
267  RestraintsAdaptor(Restraint *sf) : Restraints(1, sf) {}
268 #ifndef IMP_DOXYGEN
270  RestraintsAdaptor(const ModelsTemp &sf);
271  template <class T>
272  RestraintsAdaptor(base::internal::PointerBase<T> t)
273  : Restraints(1, get(t)) {}
274 #endif
275 };
276 
277 IMPKERNEL_END_NAMESPACE
278 
279 #endif /* IMPKERNEL_DECLARE_RESTRAINT_H */
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.
ScoringFunctions create_decomposition(ScoringFunction *sf)
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
ParticlesTemp get_input_particles(const ModelObjectsTemp &mos)
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.
ContainersTemp get_input_containers(const ModelObjectsTemp &mos)
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
IMP::kernel::Restraint Restraint
Various useful constants.
Class for storing model, its restraints, constraints, and particles.