IMP  2.2.1
The Integrative Modeling Platform
kernel/ScoringFunction.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/ScoringFunction.h
3  * \brief Storage of a model, its restraints,
4  * constraints and particles.
5  *
6  * Copyright 2007-2014 IMP Inventors. All rights reserved.
7  *
8  */
9 
10 #ifndef IMPKERNEL_SCORING_FUNCTION_H
11 #define IMPKERNEL_SCORING_FUNCTION_H
12 
13 #include <IMP/kernel/kernel_config.h>
14 #include "base_types.h"
15 #include "dependency_graph.h"
16 #include "Restraint.h"
17 #include "ModelObject.h"
18 #include <IMP/base/InputAdaptor.h>
19 #include <IMP/base/Pointer.h>
20 
21 #include <limits>
22 
23 IMPKERNEL_BEGIN_NAMESPACE
24 class Model;
25 
26 /** A ScoringFunction represents a scoring function on the model.
27  The Model has a default scoring function
28  (kernel::Model::get_model_scoring_function()), but it can be useful to use
29  others in different contexts during a samping process.
30 
31 A call to the evaluate() method prompts the following events:
32 1. determine set of ScoreState objects needed by the Restraint objects
33 being evaluated (this is cached)
34 1. call ScoreState::before_evaluate() on each of them to update
35  configuration
36 1. call Restraint::unprotected_evaluate() to compute scores
37  [and add derivatives in the particles]
38 1. [call ScoreState::after_evaluate() on each score state to update derivatives]
39 1. score returned
40 
41  \headerfile ScoringFunction.h "IMP/ScoringFunction.h"
42 
43 */
44 class IMPKERNELEXPORT ScoringFunction : public ModelObject {
45  EvaluationState es_;
46  // later make things implement inputs and return restraints
47  public:
48  typedef std::pair<double, bool> ScoreIsGoodPair;
49 
50  protected:
51  /** Do the actual work of computing the score and (optional)
52  derivatives. The list of all score states that must be updated
53  is passed.*/
54  virtual void do_add_score_and_derivatives(ScoreAccumulator sa,
55  const ScoreStatesTemp &ss) = 0;
56  ScoreAccumulator get_score_accumulator_if_below(bool deriv, double max) {
57  return ScoreAccumulator(&es_, 1.0, deriv, max, NO_MAX, true);
58  }
59  ScoreAccumulator get_score_accumulator_if_good(bool deriv) {
60  return ScoreAccumulator(&es_, 1.0, deriv, NO_MAX, NO_MAX, true);
61  }
62  ScoreAccumulator get_score_accumulator(bool deriv) {
63  return ScoreAccumulator(&es_, 1.0, deriv, NO_MAX, NO_MAX, false);
64  }
65 
66  public:
67  ScoringFunction(kernel::Model *m, std::string name);
68 
69  virtual ModelObjectsTemp do_get_outputs() const IMP_OVERRIDE {
70  return ModelObjectsTemp();
71  }
72 
73  double evaluate_if_good(bool derivatives);
74 
75  //! Evaluate and return the score
76  /**
77  Evaluate the score function and return the resulting score
78 
79  @param derivatives if true, updates the derivatives of the
80  scoring function
81  */
82  double evaluate(bool derivatives);
83 
84  double evaluate_if_below(bool derivatives, double max);
85 
86  /** Return true if the last evaluate satisfied all the restraint
87  thresholds.*/
88  bool get_had_good_score() const { return es_.good; }
89 
90  //! returns the score that was calculated in the last call
91  //! evaluate
92  double get_last_score() const { return es_.score; }
93  /** Return a set of restraints equivalent to this scoring function.
94  */
95  virtual Restraints create_restraints() const = 0;
96 };
97 
98 /** Return a list of ScoringFunction objects where each is as simple
99  as possible and evaluating the sum (and anding the good score bits)
100  is exactly like evaluating the one ScoringFunction.*/
102 
103 /** This class is to provide a consistent interface for things
104  that take ScoringFunctions as arguments.
105 
106  \note Passing an empty list of restraints should be supported, but problems
107  could arise, so be alert (the problems would not be subtle).
108 */
109 class IMPKERNELEXPORT ScoringFunctionAdaptor :
110 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
111  public base::PointerMember<ScoringFunction>
112 #else
113  public base::InputAdaptor
114 #endif
115  {
117  static ScoringFunction *get(ScoringFunction *sf) { return sf; }
118 
119  /**
120  returns a scoring function that sums a list of restraints.
121  If the list is empty, returns a null scoring function
122  that always returns 0.
123  */
124  static ScoringFunction *get(const RestraintsTemp &sf);
125 
126  /**
127  returns a scoring function that sums a list of restraints.
128  If the list is empty, returns a null scoring function
129  that always returns 0.
130  */
131  static ScoringFunction *get(const Restraints &sf);
132  static ScoringFunction *get(kernel::Model *sf);
133  static ScoringFunction *get(Restraint *sf);
134 
135  public:
137 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
138  template <class T>
139  ScoringFunctionAdaptor(base::internal::PointerBase<T> t)
140  : P(get(t)) {}
141 #endif
143  ScoringFunctionAdaptor(const RestraintsTemp &sf) : P(get(sf)) {}
144  ScoringFunctionAdaptor(const Restraints &sf) : P(get(sf)) {}
145  ScoringFunctionAdaptor(Restraint *sf) : P(get(sf)) {}
146 #ifndef IMP_DOXYGEN
147  ScoringFunctionAdaptor(kernel::Model *sf) : P(get(sf)) {}
148 #endif
149 };
150 
151 //! Print the hierarchy of restraints
152 /** The maximum accepted score (Restraint::get_maximum_score())
153  and the weight (Restraint::get_weight()) are printed for each restraint.*/
154 IMPKERNELEXPORT void show_restraint_hierarchy(ScoringFunctionAdaptor rs,
155  std::ostream &out = std::cout);
156 
157 IMPKERNEL_END_NAMESPACE
158 
159 #endif /* IMPKERNEL_SCORING_FUNCTION_H */
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
ScoringFunctions create_decomposition(ScoringFunction *sf)
IMP::base::Vector< IMP::base::WeakPointer< kernel::ModelObject > > ModelObjectsTemp
A nullptr-initialized pointer to an IMP Object.
void show_restraint_hierarchy(ScoringFunctionAdaptor rs, std::ostream &out=std::cout)
Print the hierarchy of restraints.
kernel::Restraints create_restraints(RMF::FileConstHandle fh, kernel::Model *m)
A smart pointer to a ref-counted Object that is a class memeber.
Definition: base/Pointer.h:147
Basic types used by IMP.
IMP::kernel::ScoringFunction ScoringFunction
Build dependency graphs on models.
virtual ModelObjectsTemp do_get_outputs() const
Single variable function.
Abstract base class for all restraints.
Basic types used by IMP.
IMP::kernel::ScoreAccumulator ScoreAccumulator
IMP::kernel::Model Model
Class for adding up scores during ScoringFunction evaluation.
A restraint is a term in an IMP ScoringFunction.
IMP::base::Vector< IMP::base::Pointer< ScoringFunction > > ScoringFunctions
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:72