IMP logo
IMP Reference Guide  2.17.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 
22 IMPKERNEL_BEGIN_NAMESPACE
23 
24 //! ScoreStates maintain invariants in the Model.
25 /** ScoreStates allow actions to be taken before and after the restraint
26  evaluation process. Such code can be used to, for example:
27  - log the optimization process
28  - maintain constraints (see Constraint)
29 
30  ScoreStates have two methods which are called during
31  the Model::evaluate() function
32  - before_evaluate() which is allowed to change the contents of
33  containers and the value of attributes of particles and
34  - after_evaluate() which can change particle derivatives
35 
36  The Model uses information that the ScoreState reports about
37  its input and output containers and particles to determine a safe
38  order in which all the ScoreState objects registered in the model
39  can be applied. That is, the Model will ensure that a ScoreState
40  that has Particle \c A in its output list is applied before a
41  ScoreState that has \c A in its input list.
42  For ScoreState::before_evaluate(), Input and output lists are
43  returned by the respective get_input_* and get_output_* calls.
44  For ScoreState::after_evaluate() they are reversed (see note below).
45 
46  \note The input and output sets for the ScoreState::after_evaluate()
47  functions are assumed to be the reverse of the ScoreState::before_evaluate()
48  functions. As a result, the ScoreStates are applied in opposite order
49  after evaluate. If you have a ScoreState for which this is not true,
50  consider splitting it into two parts.
51 
52  \see Model::add_score_state().
53  */
54 class IMPKERNELEXPORT ScoreState : public ModelObject {
55  int update_order_;
56  bool can_skip_;
57 
58  protected:
59  //! Set whether we can skip during model evaluation if appropriate
60  /** This should be set only once before the state is used (ideally in the
61  constructor), and can be used for ScoreStates that can safely be
62  skipped if their inputs or outputs didn't move. For example, a state
63  that expects to log every N frames should not be skipped.
64  By default, states are not skipped.
65  */
66  void set_can_skip(bool can_skip) { can_skip_ = can_skip; }
67 
68  public:
69  ScoreState(Model *m, std::string name);
70  //! Force update of the structure.
71  void before_evaluate();
72 
73  //! Do post evaluation work if needed
74  void after_evaluate(DerivativeAccumulator *accpt);
75 
76  //! Get whether this state can be skipped if its inputs/outputs didn't move
77  /** During Monte Carlo and other types of sampling that only move parts
78  of the system, ScoreStates where this returns true may be skipped at
79  model evaluation time if none of the inputs or outputs moved since
80  the last evaluation.
81  */
82  bool get_can_skip() const { return can_skip_; }
83 
84 #ifndef IMP_DOXYGEN
85  bool get_has_update_order() const { return update_order_ != -1; }
86  unsigned int get_update_order() const { return update_order_; }
87  virtual void handle_set_has_required_score_states(bool tf) override;
88 
89 #endif
90 
91  protected:
92  //! Update the state given the current state of the model.
93  /** This is also called prior to every calculation of the model score.
94  It should be implemented by ScoreStates in order to provide functionality.
95  */
96  virtual void do_before_evaluate() = 0;
97 
98  //! Do any necessary updates after the model score is calculated.
99  /** \param[in] accpt The object used to scale derivatives in the score
100  calculation, or nullptr if derivatives were not
101  requested.
102  */
103  virtual void do_after_evaluate(DerivativeAccumulator *accpt) = 0;
104 
105  IMP_REF_COUNTED_DESTRUCTOR(ScoreState);
106 };
107 
108 /** Return an appropriate (topologically sorted) order to update
109  the score states in. */
110 IMPKERNELEXPORT ScoreStatesTemp get_update_order(ScoreStatesTemp input);
111 
112 IMPKERNEL_END_NAMESPACE
113 
114 #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:66
Class for adding derivatives from restraints to the model.
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:26
bool get_can_skip() const
Get whether this state can be skipped if its inputs/outputs didn't move.
Definition: ScoreState.h:82
ScoreStates maintain invariants in the Model.
Definition: ScoreState.h:54
virtual void handle_set_has_required_score_states(bool)
Definition: ModelObject.h:71
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
Class for adding derivatives from restraints to the model.
ScoreStatesTemp get_update_order(ScoreStatesTemp input)