IMP  2.1.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 <IMP/base/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>
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  \note The input and output sets for the ScoreState::after_evaluate()
46  functions are assumed to be the reverse of the ScoreState::before_evaluate()
47  functions. As a result, the ScoreStates are applied in opposite order
48  after evaluate. If you have a ScoreState for which this is not true,
49  consider splitting it into two parts.
50  */
51 class IMPKERNELEXPORT ScoreState : public ModelObject {
52  int update_order_;
53 
54  public:
55  ScoreState(kernel::Model *m, std::string name);
56  //! Force update of the structure.
57  void before_evaluate();
58 
59  //! Do post evaluation work if needed
60  void after_evaluate(DerivativeAccumulator *accpt);
61 
62 #ifndef IMP_DOXYGEN
63  bool get_has_update_order() const { return update_order_ != -1; }
64  unsigned int get_update_order() const { return update_order_; }
65  virtual void handle_set_has_required_score_states(bool tf) IMP_OVERRIDE;
66 
67 #endif
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  virtual void do_before_evaluate() = 0;
75 
76  // Do any necessary updates after the model score is calculated.
77  /* \param[in] accpt The object used to scale derivatives in the score
78  calculation, or nullptr if derivatives were not
79  requested.
80  */
81  virtual void do_after_evaluate(DerivativeAccumulator *accpt) = 0;
82 
84 
85  public:
86  /** \deprecated_at{2.1} Use version that takes a name too.
87  */
88  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
90  /** \deprecated_at{2.1} Use version that takes a Model instead.
91  */
92  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
93  ScoreState(std::string name = "ScoreState %1%");
94  /** \deprecated_at{2.1} use get_inputs() instead.*/
95  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
97  /** \deprecated_at{2.1} use get_inputs() instead.*/
98  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
100  /** \deprecated_at{2.1} use get_outputs() instead.*/
101  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
103  /** \deprecated_at{2.1} use get_outputs() instead.*/
104  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
106 };
107 /** Return an appropriate (topoligically sorted) order to update
108  the score states in. */
109 IMPKERNELEXPORT ScoreStatesTemp get_update_order(ScoreStatesTemp input);
110 
111 IMPKERNEL_END_NAMESPACE
112 
113 #endif /* IMPKERNEL_SCORE_STATE_H */
Class for adding derivatives from restraints to the model.
Class for adding derivatives from restraints to the model.
IMP::kernel::ScoreState ScoreState
ParticlesTemp get_output_particles(const ModelObjectsTemp &mos)
virtual void handle_set_has_required_score_states(bool)
Basic types used by IMP.
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
ContainersTemp get_output_containers(const ModelObjectsTemp &mos)
ParticlesTemp get_input_particles(const ModelObjectsTemp &mos)
ScoreStates maintian invariants in the Model.
Control display of deprecation information.
Single variable function.
ContainersTemp get_input_containers(const ModelObjectsTemp &mos)
Various general useful macros for IMP.
A nullptr-initialized pointer to an Object.
For backwards compatibility.
Exception definitions and assertions.
ScoreStatesTemp get_update_order(ScoreStatesTemp input)
Class for storing model, its restraints, constraints, and particles.