IMP  2.0.1
The Integrative Modeling Platform
kernel/declare_ScoringFunction.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/declare_ScoringFunction.h
3  * \brief Storage of a model, its restraints,
4  * constraints and particles.
5  *
6  * Copyright 2007-2013 IMP Inventors. All rights reserved.
7  *
8  */
9 
10 #ifndef IMPKERNEL_DECLARE_SCORING_FUNCTION_H
11 #define IMPKERNEL_DECLARE_SCORING_FUNCTION_H
12 
13 #include <IMP/kernel/kernel_config.h>
14 #include "base_types.h"
15 #include "dependency_graph.h"
16 #include "declare_Restraint.h"
17 #include "ModelObject.h"
18 #include <IMP/base/InputAdaptor.h>
19 #include <IMP/base/tracking.h>
20 #include <IMP/base/Pointer.h>
21 
22 #include <limits>
23 
24 
25 IMPKERNEL_BEGIN_NAMESPACE
26 class Model;
27 
28 /** A ScoringFunction represents a scoring function on the model.
29  The Model has a default scoring function
30  (Model::get_model_scoring_function()), but it can be useful to use
31  others in different contexts during a samping process.
32 
33 A call to the evaluate() method prompts the following events:
34 1. determine set of ScoreState objects needed by the Restraint objects
35 being evaluated (this is cached)
36 1. call ScoreState::before_evaluate() on each of them to update
37  configuration
38 1. call Restraint::unprotected_evaluate() to compute scores
39  [and add derivatives in the particles]
40 1. [call ScoreState::after_evaluate() on each score state to update derivatives]
41 1. score returned
42 
43  \headerfile ScoringFunction.h "IMP/ScoringFunction.h"
44 
45 */
46 class IMPKERNELEXPORT ScoringFunction: public ModelObject
47  {
48  // scores states ordered in the order we will update them
49  ScoreStatesTemp ss_;
50  EvaluationState es_;
51  inline void ensure_dependencies();
52  // hack for null scoring function
53  friend class NullScoringFunction;
54  ScoringFunction(): ModelObject("NullScoringFunction%1%"),
55  es_(0.0, true) {
56  }
57  // later make things implement inputs and return restraints
58 public:
59  typedef std::pair<double, bool> ScoreIsGoodPair;
60  protected:
61  /** Do the actual work of computing the score and (optional)
62  derivatives. The list of all score states that must be updated
63  is passed.*/
64  virtual void do_add_score_and_derivatives(ScoreAccumulator sa,
65  const ScoreStatesTemp &ss)=0;
66  /** Return any score states needed in order to do scoring.
67  */
68  virtual ScoreStatesTemp get_required_score_states() const=0;
69  ScoreAccumulator get_score_accumulator_if_below(bool deriv,
70  double max){
71  return ScoreAccumulator(&es_, 1.0, deriv, max,
72  NO_MAX,
73  true);
74  }
75  ScoreAccumulator get_score_accumulator_if_good(bool deriv) {
76  return ScoreAccumulator(&es_, 1.0, deriv,
77  NO_MAX, NO_MAX, true);
78  }
79  ScoreAccumulator get_score_accumulator(bool deriv) {
80  return ScoreAccumulator(&es_, 1.0, deriv,
81  NO_MAX, NO_MAX, false);
82  }
83  public:
84  ScoringFunction(Model *m, std::string name);
85 
86  virtual ModelObjectsTemp do_get_inputs() const IMP_OVERRIDE {
87  return ModelObjectsTemp();
88  }
89  virtual ModelObjectsTemp do_get_outputs() const IMP_OVERRIDE {
90  return ModelObjectsTemp();
91  }
92  virtual void
93  do_update_dependencies() IMP_OVERRIDE;
94 
95  double evaluate_if_good(bool derivatives);
96 
97  //! Evaluate and return the score
98  /**
99  Evaluate the score function and return the resulting score
100 
101  @param derivatives if true, updates the derivatives of the
102  scoring function
103  */
104  double evaluate(bool derivatives);
105 
106  double evaluate_if_below(bool derivatives, double max);
107 
108  /** Return true if the last evaluate satisfied all the restraint
109  thresholds.*/
110  bool get_had_good_score() const {
111  return es_.good;
112  }
113 
114  //! returns the score that was calculated in the last call
115  //! evaluate
116  double get_last_score() const {
117  return es_.score;
118  }
119  /** Return a set of restraints equivalent to this scoring function.
120  */
121  virtual Restraints create_restraints() const=0;
122 
123  /** Return the score states needed to evaluate this ScoringFunction.*/
124  const ScoreStatesTemp& get_score_states();
125 
126  void clear_caches();
127 };
128 
129 
130 /** Return a list of ScoringFunction objects where each is as simple
131  as possible and evaluating the sum (and anding the good score bits)
132  is exactly like evaluating the one ScoringFunction.*/
134 
135 /** This class is to provide a consisted interface for things
136  that take ScoringFunctions as arguments.
137 
138  \note Passing an empty list of restraints should be supported, but problems
139  could arise, so be alert (the problems would not be subtle).
140 */
141 class IMPKERNELEXPORT ScoringFunctionAdaptor:
142 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
143  public base::OwnerPointer<ScoringFunction>
144 #else
145  public base::InputAdaptor
146 #endif
147 {
149  static ScoringFunction* get(ScoringFunction *sf) {
150  return sf;
151  }
152 
153  /**
154  returns a scoring function that sums a list of restraints.
155  If the list is empty, returns a null scoring function
156  that always returns 0.
157  */
158  static ScoringFunction* get(const RestraintsTemp &sf);
159 
160  /**
161  returns a scoring function that sums a list of restraints.
162  If the list is empty, returns a null scoring function
163  that always returns 0.
164  */
165  static ScoringFunction* get(const Restraints &sf);
166  static ScoringFunction* get(Model *sf);
167  static ScoringFunction* get(Restraint *sf);
168  public:
170 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
171  template <class T>
172  ScoringFunctionAdaptor(base::internal::PointerBase<T> t):
173  P(get(t)){}
174 #endif
176  ScoringFunctionAdaptor(const RestraintsTemp &sf): P(get(sf)){}
177  ScoringFunctionAdaptor(const Restraints &sf): P(get(sf)){}
178  ScoringFunctionAdaptor(Model *sf): P(get(sf)){}
179  ScoringFunctionAdaptor(Restraint *sf): P(get(sf)){}
180 };
181 
182 //! Print the hierarchy of restraints
183 /** The maximum accepted score (Restraint::get_maximum_score())
184  and the weight (Restraint::get_weight()) are printed for each restraint.*/
185 IMPKERNELEXPORT void show_restraint_hierarchy(ScoringFunctionAdaptor rs,
186  std::ostream &out=std::cout);
187 
188 
189 IMPKERNEL_END_NAMESPACE
190 
191 #endif /* IMPKERNEL_DECLARE_SCORING_FUNCTION_H */