IMP  2.0.0
The Integrative Modeling Platform
kernel/ScoreState.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/ScoreState.h \brief Shared score state.
3  *
4  * Copyright 2007-2013 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/kernel_config.h>
12 #include "WeakPointer.h"
13 #include "DerivativeAccumulator.h"
14 #include "utility.h"
15 #include "ModelObject.h"
16 #include "base_types.h"
17 #include <IMP/base/check_macros.h>
18 #include <IMP/base/deprecation_macros.h>
19 #include <IMP/base/ref_counted_macros.h>
20 #include <iostream>
21 
22 IMPKERNEL_BEGIN_NAMESPACE
23 //! ScoreStates maintian invariants in the Model.
24 /** ScoreStates allow actions to be taken before and after the restraint
25  evaluation process. Such code can be used to, for example:
26  - log the optimization process
27  - maintain constraints (see Constraint)
28 
29  ScoreStates have two methods which are called during
30  the Model::evaluate() function
31  - before_evaluate() which is allowed to change the contents of
32  containers and the value of attributes of particles and
33  - after_evaluate() which can change particle derivatives
34 
35  The Model uses information that the ScoreState reports about
36  its input and output containers and particles to determine a safe
37  order in which all the ScoreState objects registered in the model
38  can be applied. That is, the Model will ensure that a ScoreState
39  that has Particle \c A in its output list is applied before a
40  ScoreState that has \c A in its input list.
41  For ScoreState::before_evaluate(), Input and output lists are
42  returned by the respective get_input_* and get_output_* calls.
43  For ScoreState::after_evaluate() they are reversed (see note below).
44 
45 
46  \note If no acceptable order exists, an exception will be thrown
47  and the set of ScoreState objects creating the loop will be
48  reported.
49 
50  \note The input and output sets for the ScoreState::after_evaluate()
51  functions are assumed to be the reverse of the ScoreState::before_evaluate()
52  functions. As a result, the ScoreStates are applied in opposite order
53  after evaluate. If you have a ScoreState for which this is not true,
54  consider splitting it into two parts.
55  */
56 class IMPKERNELEXPORT ScoreState : public ModelObject
57 {
58 public:
59 #ifndef IMP_DOXYGEN
60  ScoreState(std::string name="ScoreState %1%");
61 #endif
62  ScoreState(Model *m, std::string name="ScoreState %1%");
63  //! Force update of the structure.
64  void before_evaluate();
65 
66  //! Do post evaluation work if needed
67  void after_evaluate(DerivativeAccumulator *accpt);
68 
69 protected:
70  // Update the state given the current state of the model.
71  /* This is also called prior to every calculation of the model score.
72  It should be implemented by ScoreStates in order to provide functionality.
73 
74  \note This can't have the same name as the public function due to the
75  way C++ handles overloading and name lookups--if only one is implemented
76  in the child class it will only find that one.
77  */
78  virtual void do_before_evaluate() = 0;
79 
80  // Do any necessary updates after the model score is calculated.
81  /* \param[in] accpt The object used to scale derivatives in the score
82  calculation, or nullptr if derivatives were not
83  requested.
84  */
85  virtual void do_after_evaluate(DerivativeAccumulator *accpt)=0;
86 
87  IMP_REF_COUNTED_NONTRIVIAL_DESTRUCTOR(ScoreState);
88 
89 public:
90 #if IMP_HAS_DEPRECATED
91  /** \deprecated use get_inputs() instead.*/
92  IMP_DEPRECATED_WARN ParticlesTemp get_input_particles() const;
93  /** \deprecated use get_inputs() instead.*/
94  IMP_DEPRECATED_WARN ContainersTemp get_input_containers() const;
95  /** \deprecated use get_outputs() instead.*/
96  IMP_DEPRECATED_WARN ParticlesTemp get_output_particles() const;
97  /** \deprecated use get_outputs() instead.*/
98  IMP_DEPRECATED_WARN ContainersTemp get_output_containers() const;
99 #endif
100 protected:
101  virtual void do_update_dependencies() IMP_OVERRIDE;
102  private:
103 
104 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
105 public:
106 #endif
107  int order_;
108 };
109 
110 /** Return the passed list of score states ordered based on how they need to
111  be ordered during update calls.*/
112 IMPKERNELEXPORT ScoreStatesTemp get_update_order( ScoreStatesTemp input);
113 
114 IMPKERNEL_END_NAMESPACE
115 
116 
117 #endif /* IMPKERNEL_SCORE_STATE_H */