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