IMP logo
IMP Reference Guide  2.19.0
The Integrative Modeling Platform
ScoreState.h
Go to the documentation of this file.
1 /**
2  * \file IMP/ScoreState.h \brief Shared score state.
3  *
4  * Copyright 2007-2022 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPKERNEL_SCORE_STATE_H
9 #define IMPKERNEL_SCORE_STATE_H
10 
11 #include <IMP/kernel_config.h>
12 #include <IMP/WeakPointer.h>
13 #include "DerivativeAccumulator.h"
14 #include "utility.h"
15 #include "ModelObject.h"
16 #include "base_types.h"
17 #include <IMP/check_macros.h>
18 #include <IMP/deprecation_macros.h>
19 #include <IMP/ref_counted_macros.h>
20 #include <iostream>
21 #include <cereal/access.hpp>
22 #include <cereal/types/base_class.hpp>
23 
24 IMPKERNEL_BEGIN_NAMESPACE
25 
26 //! ScoreStates maintain invariants in the Model.
27 /** ScoreStates allow actions to be taken before and after the restraint
28  evaluation process. Such code can be used to, for example:
29  - log the optimization process
30  - maintain constraints (see Constraint)
31 
32  ScoreStates have two methods which are called during
33  the Model::evaluate() function
34  - before_evaluate() which is allowed to change the contents of
35  containers and the value of attributes of particles and
36  - after_evaluate() which can change particle derivatives
37 
38  The Model uses information that the ScoreState reports about
39  its input and output containers and particles to determine a safe
40  order in which all the ScoreState objects registered in the model
41  can be applied. That is, the Model will ensure that a ScoreState
42  that has Particle \c A in its output list is applied before a
43  ScoreState that has \c A in its input list.
44  For ScoreState::before_evaluate(), Input and output lists are
45  returned by the respective get_input_* and get_output_* calls.
46  For ScoreState::after_evaluate() they are reversed (see note below).
47 
48  \note The input and output sets for the ScoreState::after_evaluate()
49  functions are assumed to be the reverse of the ScoreState::before_evaluate()
50  functions. As a result, the ScoreStates are applied in opposite order
51  after evaluate. If you have a ScoreState for which this is not true,
52  consider splitting it into two parts.
53 
54  \see Model::add_score_state().
55  */
56 class IMPKERNELEXPORT ScoreState : public ModelObject {
57  int update_order_;
58  bool can_skip_;
59 
60  friend class cereal::access;
61 
62  template<class Archive> void serialize(Archive &ar) {
63  ar(cereal::base_class<ModelObject>(this), can_skip_);
64  if (std::is_base_of<cereal::detail::InputArchiveBase, Archive>::value) {
65  update_order_ = -1;
66  }
67  }
68 
69  protected:
70  //! Set whether we can skip during model evaluation if appropriate
71  /** This should be set only once before the state is used (ideally in the
72  constructor), and can be used for ScoreStates that can safely be
73  skipped if their inputs or outputs didn't move. For example, a state
74  that expects to log every N frames should not be skipped.
75  By default, states are not skipped.
76  */
77  void set_can_skip(bool can_skip) { can_skip_ = can_skip; }
78 
79  public:
80  ScoreState(Model *m, std::string name);
81  ScoreState() {}
82  //! Force update of the structure.
83  void before_evaluate();
84 
85  //! Do post evaluation work if needed
86  void after_evaluate(DerivativeAccumulator *accpt);
87 
88  //! Get whether this state can be skipped if its inputs/outputs didn't move
89  /** During Monte Carlo and other types of sampling that only move parts
90  of the system, ScoreStates where this returns true may be skipped at
91  model evaluation time if none of the inputs or outputs moved since
92  the last evaluation.
93  */
94  bool get_can_skip() const { return can_skip_; }
95 
96 #ifndef IMP_DOXYGEN
97  bool get_has_update_order() const { return update_order_ != -1; }
98  unsigned int get_update_order() const { return update_order_; }
99  virtual void handle_set_has_required_score_states(bool tf) override;
100 
101 #endif
102 
103  protected:
104  //! Update the state given the current state of the model.
105  /** This is also called prior to every calculation of the model score.
106  It should be implemented by ScoreStates in order to provide functionality.
107  */
108  virtual void do_before_evaluate() = 0;
109 
110  //! Do any necessary updates after the model score is calculated.
111  /** \param[in] accpt The object used to scale derivatives in the score
112  calculation, or nullptr if derivatives were not
113  requested.
114  */
115  virtual void do_after_evaluate(DerivativeAccumulator *accpt) = 0;
116 
117  IMP_REF_COUNTED_DESTRUCTOR(ScoreState);
118 };
119 
120 /** Return an appropriate (topologically sorted) order to update
121  the score states in. */
122 IMPKERNELEXPORT ScoreStatesTemp get_update_order(ScoreStatesTemp input);
123 
124 #ifndef SWIG
125 /** Return an appropriate (topologically sorted) order to update
126  the score states in. */
127 IMPKERNELEXPORT ScoreStatesTemp get_update_order(std::set<ScoreState*> input);
128 #endif
129 
130 IMPKERNEL_END_NAMESPACE
131 
132 #endif /* IMPKERNEL_SCORE_STATE_H */
Control display of deprecation information.
Macros to help with reference counting.
Basic types used by IMP.
void set_can_skip(bool can_skip)
Set whether we can skip during model evaluation if appropriate.
Definition: ScoreState.h:77
Class for adding derivatives from restraints to the model.
ScoreStatesTemp get_update_order(std::set< ScoreState * > input)
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Set up destructor for a ref counted object.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:28
bool get_can_skip() const
Get whether this state can be skipped if its inputs/outputs didn't move.
Definition: ScoreState.h:94
ScoreStates maintain invariants in the Model.
Definition: ScoreState.h:56
virtual void handle_set_has_required_score_states(bool)
Definition: ModelObject.h:93
A weak pointer to an Object or RefCountedObject.
For backwards compatibility.
Base class for objects in a Model that depend on other objects.
Helper macros for throwing and handling exceptions.
IMP::Vector< IMP::WeakPointer< ScoreState > > ScoreStatesTemp
Definition: base_types.h:97
ScoreStatesTemp get_update_order(ScoreStatesTemp input)