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