IMP logo
IMP Reference Guide  2.6.0
The Integrative Modeling Platform
OptimizerState.h
Go to the documentation of this file.
1 /**
2  * \file IMP/OptimizerState.h \brief Shared optimizer state.
3  *
4  * Copyright 2007-2016 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_config.h>
12 #include "ModelObject.h"
13 #include <IMP/WeakPointer.h>
14 #include <IMP/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 An OptimizerState 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 Optimizer::optimize().
37 
38  \note When logging is VERBOSE, the state should print enough information
39  in update() to reproduce the entire flow of data in update. When
40  logging is TERSE the state 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  //! Constructor.
51  /** Constructs an optimizer state whose update() method is invoked
52  every time that a set of model coordinates is committed
53  by an optimizer.
54 
55  @param m the model to which this optimizer state is associated
56  @param name the name of the object
57  @note An OptimizerState may become periodic via its set_period()
58  method.
59  */
60  OptimizerState(Model* m, std::string name);
61 
62  //! Called when the Optimizer accepts a new conformation
63  /**
64  This method is called by owning optimizers every time they commit.
65  However, if set_period(p) was invoked, it calls do_update() only
66  every p times it is called (by any optimizer).
67 
68  @note Overriding this method is deprecated; override do_update() instead.
69  */
70  virtual void update();
71 
72  //! Called by an Optimizer to signal begin/end of an optimize run.
73  /** At the beginning of an optimize run, set_is_optimizing(true) is
74  called. At the end, set_is_optimizing(false) is called.
75 
76  \note Do not override; override do_set_is_optimizing() instead.
77  */
78  virtual void set_is_optimizing(bool);
79 
80  Optimizer* get_optimizer() const {
81  IMP_INTERNAL_CHECK(optimizer_,
82  "Must call set_optimizer before get_optimizer on state");
83  return optimizer_.get();
84  }
85 
86  //! Set the periodicity of this state.
87  /** This causes update() to invoke do_update() only every p calls
88  to update() rather than on every call (p=1). Note that this
89  periodicity is shared by all optimizers that own this
90  OptimizerState object.
91 
92  @param p periodicity
93  */
94  void set_period(unsigned int p);
95 
96  //! Get the periodicity of this state.
97  /** @return the periodicity of this state (how many calls to update()
98  are required to invoke do_update())
99  */
100  unsigned int get_period() const { return period_; }
101 
102  //! Reset counters, as if at the start of an optimize run.
103  virtual void reset();
104 
105  //! Force the state to perform its action now, ignoring the periodicity.
106  void update_always();
107 
108  //! Return the number of times do_update() has been called
109  unsigned int get_number_of_updates() const { return update_number_; }
110 
111  //! Set the counter of number of times do_update() has been called
112  void set_number_of_updates(unsigned int n) { update_number_ = n; }
113 
115 
116  protected:
117  /** This method is called every get_period() update calls. The number of
118  times this method has been called since the last reset or start of the
119  optimization run is passed.*/
120  virtual void do_update(unsigned int) { update(); }
121 
122  virtual void do_set_is_optimizing(bool) {}
123 
125  return ModelObjectsTemp();
126  }
128  return ModelObjectsTemp();
129  }
130 
131  private:
133  bool is_optimizing_;
134 };
135 
136 IMPKERNEL_END_NAMESPACE
137 
138 #endif /* IMPKERNEL_OPTIMIZER_STATE_H */
#define IMP_FINAL
Have the compiler report an error if anything overrides this method.
unsigned int get_period() const
Get the periodicity of this state.
virtual ModelObjectsTemp do_get_inputs() const
virtual void do_update(unsigned int)
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Ref counted objects should have private destructors.
A weak pointer to an Object or RefCountedObject.
Definition: WeakPointer.h:32
#define IMP_INTERNAL_CHECK(expr, message)
An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown.
Definition: check_macros.h:139
IMP::Vector< IMP::WeakPointer< ModelObject > > ModelObjectsTemp
Definition: base_types.h:82
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
Base class for all optimizers.
Definition: Optimizer.h:46
A nullptr-initialized pointer to an Object.
Single variable function.
void set_number_of_updates(unsigned int n)
Set the counter of number of times do_update() has been called.
A shared base class to help in debugging and things.
Shared optimizer state that is invoked upon commitment of new coordinates.
virtual ModelObjectsTemp do_get_outputs() const
unsigned int get_number_of_updates() const
Return the number of times do_update() has been called.
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.