IMP  2.1.0
The Integrative Modeling Platform
kernel/OptimizerState.h
Go to the documentation of this file.
1 /**
2  * \file IMP/kernel/OptimizerState.h \brief Shared optimizer state.
3  *
4  * Copyright 2007-2013 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPKERNEL_OPTIMIZER_STATE_H
9 #define IMPKERNEL_OPTIMIZER_STATE_H
10 
11 #include <IMP/kernel/kernel_config.h>
12 #include "ModelObject.h"
13 #include <IMP/base/WeakPointer.h>
14 #include <IMP/base/Object.h>
15 
16 #include <iostream>
17 
18 IMPKERNEL_BEGIN_NAMESPACE
19 
20 class Optimizer;
21 
22 //! Shared optimizer state that is invoked upon commitment of new coordinates.
23 /** An OptimizerState update() method is called every time that an
24  owning Optimizer commits to a new set of coordinates. The update()
25  method, in turn, invokes do_update(), which can be overridden by
26  inheriting classes.
27 
28  @note An OptimizerState may have periodicity by its set_period() method
29 
30  @note An OptimizerState is added to an Optimizer object by calling
31  Optimizer::add_optimizer_state().
32 
33  @note Optimizer states may change the values of particle
34  attributes. However, changes to whether an attribute is optimized
35  or not may not be picked up by the Optimizer until the next call
36  to optimize.
37 
38  \note When logging is VERBOSE, state should print enough information
39  in evaluate to reproduce the the entire flow of data in update. When
40  logging is TERSE the restraint should print out only a constant number
41  of lines per update call.
42  */
43 class IMPKERNELEXPORT OptimizerState : public ModelObject {
44  friend class Optimizer;
45  unsigned int period_, call_number_, update_number_;
46 
47  void set_optimizer(Optimizer* optimizer);
48 
49  public:
50  /** constructs an optimizer state whose update() method is invoked
51  every time that a set of model coordinates is committed
52  by an optimizer.
53 
54  @param m the model to which this optimizer state is associated
55  @param name the name of the object
56  @note An optimizer state may become periodic via its set_period()
57  method.
58  */
59  OptimizerState(kernel::Model* m, std::string name);
60 
61  /** \deprecated_at{2.1} Use the constructor that takes a Model. */
62  IMPKERNEL_DEPRECATED_FUNCTION_DECL(2.1)
63  OptimizerState(std::string name = "OptimizerState %1%");
64 
65  //! Called when the Optimizer accepts a new conformation
66  /**
67  This method is called by owning optimizers every time they commit.
68  However, if set_period(p) was invoked, it calls do_update() only
69  every p times it is called (by any optimizer).
70 
71  @note Overriding this method is deprecated, override do_update() instead.
72  */
73  virtual void update();
74 
75  /** Called with true at the beginning of an optimizing run and with
76  false at the end.
77 
78  \note Do not override, override do_set_is_optimizing() instead.
79  */
80  virtual void set_is_optimizing(bool);
81 
82  Optimizer* get_optimizer() const {
83  IMP_INTERNAL_CHECK(optimizer_,
84  "Must call set_optimizer before get_optimizer on state");
85  return optimizer_.get();
86  }
87 
88  /**
89  Causes update() invoke do_update() only every p calls to update()
90  instead of the default p=1. Note that this periodicity is shared
91  by all optimizers that own this OptimizerState object.
92 
93  @param p periodicity
94  */
95  void set_period(unsigned int p);
96 
97  /**
98  @return the periodicity of the optimizer (how many calls to update()
99  are required to invoke do_update()
100  */
101  unsigned int get_period() const { return period_; }
102 
103  /** Reset the phase to 0 and set the call number to 0 too.*/
104  virtual void reset();
105 
106  /** Force the optimizer state to perform its action now, ignoring the
107  phase.
108  */
109  void update_always();
110 
111  //! Return the number of times update has been called
112  unsigned int get_number_of_updates() const { return update_number_; }
113 
114  //! Set the counter
115  void set_number_of_updates(unsigned int n) { update_number_ = n; }
116 
117  IMP_REF_COUNTED_DESTRUCTOR(OptimizerState);
118 
119  protected:
120  /** This method is called every get_period() update calls. The number of
121  times this method has been called since the last reset or start of the
122  optimization run is passed.*/
123  virtual void do_update(unsigned int) { update(); }
124 
125  virtual void do_set_is_optimizing(bool) {}
126 
127  virtual ModelObjectsTemp do_get_inputs() const IMP_OVERRIDE {
128  return ModelObjectsTemp();
129  }
130  virtual ModelObjectsTemp do_get_outputs() const IMP_OVERRIDE IMP_FINAL {
131  return ModelObjectsTemp();
132  }
133 
134  private:
136  bool is_optimizing_;
137 };
138 
139 IMPKERNEL_END_NAMESPACE
140 
141 #endif /* IMPKERNEL_OPTIMIZER_STATE_H */
A weak pointer to an Object or RefCountedObject.
IMP::base::Vector< IMP::base::WeakPointer< kernel::ModelObject > > ModelObjectsTemp
virtual void do_update(unsigned int)
unsigned int get_period() const
Shared optimizer state that is invoked upon commitment of new coordinates.
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
IMP::kernel::Optimizer Optimizer
virtual ModelObjectsTemp do_get_inputs() const
Single variable function.
#define IMP_INTERNAL_CHECK(expr, message)
An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown.
Base class for all optimizers.
A nullptr-initialized pointer to an Object.
unsigned int get_number_of_updates() const
Return the number of times update has been called.
virtual ModelObjectsTemp do_get_outputs() const
IMP::kernel::OptimizerState OptimizerState
A shared base class to help in debugging and things.
Class for storing model, its restraints, constraints, and particles.
void set_number_of_updates(unsigned int n)
Set the counter.