IMP logo
IMP Reference Guide  develop.63e71f5352,2022/07/06
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-2022 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 "internal/moved_particles_cache.h"
18 #include <IMP/InputAdaptor.h>
19 #include <IMP/Pointer.h>
20 
21 #include <limits>
22 
23 IMPKERNEL_BEGIN_NAMESPACE
24 class Model;
25 
26 //! Represents a scoring function on the model.
27 /**
28 A call to the evaluate() method prompts the following events:
29 1. determine set of ScoreState objects needed by the Restraint objects
30 being evaluated (this is cached)
31 2. call ScoreState::before_evaluate() on each of them to update
32  configuration
33 3. call Restraint::unprotected_evaluate() to compute scores
34  [and add derivatives in the particles, if requested]
35 4. [call ScoreState::after_evaluate() on each score state to update derivatives]
36 5. return the score
37 
38  \headerfile ScoringFunction.h "IMP/ScoringFunction.h"
39 
40 */
41 class IMPKERNELEXPORT ScoringFunction : public ModelObject {
42  EvaluationState es_;
43  // cache of ScoreStates that are affected by each moved particle,
44  // used for evaluate_moved() and related functions
45  internal::MovedParticlesScoreStateCache moved_particles_cache_;
46  // time when moved_particles_cache_ was last updated, or 0
47  unsigned moved_particles_cache_age_;
48 
49  ScoreStatesTemp get_moved_required_score_states(
50  const ParticleIndexes &moved_pis,
51  const ParticleIndexes &reset_pis);
52 
53  // later make things implement inputs and return restraints
54  public:
55  typedef std::pair<double, bool> ScoreIsGoodPair;
56 
57  protected:
58  /** Do the actual work of computing the score and (optional)
59  derivatives. The list of all score states that must be updated
60  is passed.*/
61  virtual void do_add_score_and_derivatives(ScoreAccumulator sa,
62  const ScoreStatesTemp &ss) = 0;
63 
64  //! Score when only some particles have moved.
65  /** \see do_add_score_and_derivatives()
66  */
68  ScoreAccumulator sa, const ParticleIndexes &moved_pis,
69  const ParticleIndexes &reset_pis,
70  const ScoreStatesTemp &ss) {
71  IMP_UNUSED(moved_pis);
72  IMP_UNUSED(reset_pis);
73  do_add_score_and_derivatives(sa, ss);
74  }
75 
76  ScoreAccumulator get_score_accumulator_if_below(bool deriv, double max) {
77  return ScoreAccumulator(&es_, 1.0, deriv, max, NO_MAX, true);
78  }
79  ScoreAccumulator get_score_accumulator_if_good(bool deriv) {
80  return ScoreAccumulator(&es_, 1.0, deriv, NO_MAX, NO_MAX, true);
81  }
82  ScoreAccumulator get_score_accumulator(bool deriv) {
83  return ScoreAccumulator(&es_, 1.0, deriv, NO_MAX, NO_MAX, false);
84  }
85 
86  public:
87  ScoringFunction(Model *m, std::string name);
88 
89  virtual ModelObjectsTemp do_get_outputs() const override {
90  return ModelObjectsTemp();
91  }
92 
93  double evaluate_if_good(bool derivatives);
94 
95  //! Evaluate and return the score
96  /** \return the resulting score
97 
98  @param derivatives if true, updates the derivatives of the
99  scoring function
100  */
101  double evaluate(bool derivatives);
102 
103  //! Score when some particles have moved.
104  /** This should behave identically to evaluate() but may be more
105  efficient if it can skip restraint terms that involve unchanged particles.
106 
107  \see IMP::core::MonteCarlo::set_score_moved
108 
109  \param moved_pis Particles that have moved since the last
110  scoring function evaluation.
111  \param reset_pis Particles that have moved, but back to the
112  positions they had at the last-but-one evaluation
113  (e.g. due to a rejected Monte Carlo move).
114 
115  \see evaluate()
116  */
117  double evaluate_moved(bool derivatives, const ParticleIndexes &moved_pis,
118  const ParticleIndexes &reset_pis);
119 
120  double evaluate_moved_if_below(
121  bool derivatives, const ParticleIndexes &moved_pis,
122  const ParticleIndexes &reset_pis, double max);
123 
124  double evaluate_moved_if_good(
125  bool derivatives, const ParticleIndexes &moved_pis,
126  const ParticleIndexes &reset_pis);
127 
128  double evaluate_if_below(bool derivatives, double max);
129 
130  /** Return true if the last evaluate satisfied all the restraint
131  thresholds.*/
132  bool get_had_good_score() const { return es_.good; }
133 
134  //! returns the score that was calculated in the last evaluate call
135  double get_last_score() const { return es_.score; }
136  //! Return a set of restraints equivalent to this scoring function.
137  virtual Restraints create_restraints() const = 0;
138 };
139 
140 /** Return a list of ScoringFunction objects where each is as simple
141  as possible and evaluating the sum (and anding the good score bits)
142  is exactly like evaluating the one ScoringFunction.*/
143 IMPKERNELEXPORT ScoringFunctions create_decomposition(ScoringFunction *sf);
144 
145 /** This class is to provide a consistent interface for things
146  that take ScoringFunctions as arguments.
147 
148  \note Passing an empty list of restraints should be supported, but problems
149  could arise, so be alert (the problems would not be subtle).
150 */
151 class IMPKERNELEXPORT ScoringFunctionAdaptor :
152 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
153  public PointerMember<ScoringFunction>
154 #else
155  public InputAdaptor
156 #endif
157  {
159  static ScoringFunction *get(ScoringFunction *sf) { return sf; }
160 
161  /**
162  returns a scoring function that sums a list of restraints.
163  If the list is empty, returns a null scoring function
164  that always returns 0.
165  */
166  static ScoringFunction *get(const RestraintsTemp &sf);
167 
168  /**
169  returns a scoring function that sums a list of restraints.
170  If the list is empty, returns a null scoring function
171  that always returns 0.
172  */
173  static ScoringFunction *get(const Restraints &sf);
174  static ScoringFunction *get(Restraint *sf);
175 
176  public:
178 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
179  template <class T>
180  ScoringFunctionAdaptor(internal::PointerBase<T> t)
181  : P(get(t)) {}
182 #endif
184  ScoringFunctionAdaptor(const RestraintsTemp &sf) : P(get(sf)) {}
185  ScoringFunctionAdaptor(const Restraints &sf) : P(get(sf)) {}
186  ScoringFunctionAdaptor(Restraint *sf) : P(get(sf)) {}
187 };
188 
189 //! Print the hierarchy of restraints
190 /** The maximum accepted score (Restraint::get_maximum_score())
191  and the weight (Restraint::get_weight()) are printed for each restraint.*/
192 IMPKERNELEXPORT void show_restraint_hierarchy(ScoringFunctionAdaptor rs,
193  std::ostream &out = std::cout);
194 
195 IMPKERNEL_END_NAMESPACE
196 
197 #endif /* IMPKERNEL_SCORING_FUNCTION_H */
IMP::Vector< IMP::Pointer< ScoringFunction > > ScoringFunctions
Definition: base_types.h:98
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
Basic types used by IMP.
virtual void do_add_score_and_derivatives_moved(ScoreAccumulator sa, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis, const ScoreStatesTemp &ss)
Score when only some particles have moved.
A more IMP-like version of the std::vector.
Definition: Vector.h:40
ScoringFunctions create_decomposition(ScoringFunction *sf)
IMP::Vector< IMP::WeakPointer< ModelObject > > ModelObjectsTemp
Definition: base_types.h:89
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:26
Convenience class to accept multiple input types.
#define IMP_UNUSED(variable)
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
Base class for objects in a Model that depend on other objects.
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.
Convenience class to accept multiple input types.
Definition: InputAdaptor.h:25
virtual ModelObjectsTemp do_get_outputs() const override
Build dependency graphs on models.
bool get_had_good_score() const
A restraint is a term in an IMP ScoringFunction.
Definition: Restraint.h:53