IMP  2.3.0
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 //! 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 sampling 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 
70  return ModelObjectsTemp();
71  }
72 
73  double evaluate_if_good(bool derivatives);
74 
75  //! Evaluate and return the score
76  /** \return the resulting score
77 
78  @param derivatives if true, updates the derivatives of the
79  scoring function
80  */
81  double evaluate(bool derivatives);
82 
83  double evaluate_if_below(bool derivatives, double max);
84 
85  /** Return true if the last evaluate satisfied all the restraint
86  thresholds.*/
87  bool get_had_good_score() const { return es_.good; }
88 
89  //! returns the score that was calculated in the last evaluate call
90  double get_last_score() const { return es_.score; }
91  //! Return a set of restraints equivalent to this scoring function.
92  virtual Restraints create_restraints() const = 0;
93 };
94 
95 /** Return a list of ScoringFunction objects where each is as simple
96  as possible and evaluating the sum (and anding the good score bits)
97  is exactly like evaluating the one ScoringFunction.*/
99 
100 /** This class is to provide a consistent interface for things
101  that take ScoringFunctions as arguments.
102 
103  \note Passing an empty list of restraints should be supported, but problems
104  could arise, so be alert (the problems would not be subtle).
105 */
106 class IMPKERNELEXPORT ScoringFunctionAdaptor :
107 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
108  public base::PointerMember<ScoringFunction>
109 #else
110  public base::InputAdaptor
111 #endif
112  {
114  static ScoringFunction *get(ScoringFunction *sf) { return sf; }
115 
116  /**
117  returns a scoring function that sums a list of restraints.
118  If the list is empty, returns a null scoring function
119  that always returns 0.
120  */
121  static ScoringFunction *get(const RestraintsTemp &sf);
122 
123  /**
124  returns a scoring function that sums a list of restraints.
125  If the list is empty, returns a null scoring function
126  that always returns 0.
127  */
128  static ScoringFunction *get(const Restraints &sf);
129  static ScoringFunction *get(kernel::Model *sf);
130  static ScoringFunction *get(Restraint *sf);
131 
132  public:
134 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
135  template <class T>
136  ScoringFunctionAdaptor(base::internal::PointerBase<T> t)
137  : P(get(t)) {}
138 #endif
140  ScoringFunctionAdaptor(const RestraintsTemp &sf) : P(get(sf)) {}
141  ScoringFunctionAdaptor(const Restraints &sf) : P(get(sf)) {}
142  ScoringFunctionAdaptor(Restraint *sf) : P(get(sf)) {}
143 #ifndef IMP_DOXYGEN
144  ScoringFunctionAdaptor(kernel::Model *sf) : P(get(sf)) {}
145 #endif
146 };
147 
148 //! Print the hierarchy of restraints
149 /** The maximum accepted score (Restraint::get_maximum_score())
150  and the weight (Restraint::get_weight()) are printed for each restraint.*/
151 IMPKERNELEXPORT void show_restraint_hierarchy(ScoringFunctionAdaptor rs,
152  std::ostream &out = std::cout);
153 
154 IMPKERNEL_END_NAMESPACE
155 
156 #endif /* IMPKERNEL_SCORING_FUNCTION_H */
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
double get_last_score() const
returns the score that was calculated in the last evaluate call
ScoringFunctions create_decomposition(ScoringFunction *sf)
IMP::base::Vector< IMP::base::WeakPointer< kernel::ModelObject > > ModelObjectsTemp
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 member.
Definition: Pointer.h:147
Basic types used by IMP.
IMP::kernel::ScoringFunction ScoringFunction
Build dependency graphs on models.
virtual ModelObjectsTemp do_get_outputs() const
Represents a scoring function on the model.
Basic types used by IMP.
Single variable function.
Abstract base class for all restraints.
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.
A nullptr-initialized pointer to an IMP Object.
IMP::base::Vector< IMP::base::Pointer< ScoringFunction > > ScoringFunctions
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:73