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