IMP logo
IMP Reference Guide  2.19.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-2022 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 #include <cereal/access.hpp>
16 #include <cereal/types/base_class.hpp>
17 #include <iostream>
18 
19 IMPKERNEL_BEGIN_NAMESPACE
20 
21 class Optimizer;
22 
23 //! Shared optimizer state that is invoked upon commitment of new coordinates.
24 /** An OptimizerState update() method is called every time that an
25  owning Optimizer commits to a new set of coordinates. (For example, this
26  is typically every step during molecular dynamics, or every accepted move
27  during Monte Carlo.) The update() method, in turn, invokes do_update(),
28  which can be overridden by inheriting classes.
29 
30  @note An OptimizerState may have periodicity by its set_period() method.
31 
32  @note An OptimizerState is added to an Optimizer object by calling
33  Optimizer::add_optimizer_state().
34 
35  @note An OptimizerState may change the values of particle
36  attributes. However, changes to whether an attribute is optimized
37  or not may not be picked up by the Optimizer until the next call
38  to Optimizer::optimize().
39 
40  \note When logging is VERBOSE, the state should print enough information
41  in update() to reproduce the entire flow of data in update. When
42  logging is TERSE the state should print out only a constant number
43  of lines per update call.
44  */
45 class IMPKERNELEXPORT OptimizerState : public ModelObject {
46  friend class Optimizer;
47  unsigned int period_, call_number_, update_number_;
48 
49  friend class cereal::access;
50 
51  template<class Archive> void serialize(Archive &ar) {
52  ar(cereal::base_class<ModelObject>(this), period_, call_number_,
53  update_number_, is_optimizing_);
54  if (std::is_base_of<cereal::detail::InputArchiveBase, Archive>::value) {
55  optimizer_ = nullptr;
56  }
57  }
58 
59  void set_optimizer(Optimizer* optimizer);
60 
61  public:
62  //! Constructor.
63  /** Constructs an optimizer state whose update() method is invoked
64  every time that a set of model coordinates is committed
65  by an optimizer.
66 
67  @param m the model to which this optimizer state is associated
68  @param name the name of the object
69  @note An OptimizerState may become periodic via its set_period()
70  method.
71  */
72  OptimizerState(Model* m, std::string name);
74 
75  //! Called when the Optimizer accepts a new conformation
76  /**
77  This method is called by owning optimizers every time they commit.
78  However, if set_period(p) was invoked, it calls do_update() only
79  every p times it is called (by any optimizer).
80 
81  @note Overriding this method is deprecated; override do_update() instead.
82  */
83  virtual void update();
84 
85  //! Called by an Optimizer to signal begin/end of an optimize run.
86  /** At the beginning of an optimize run, set_is_optimizing(true) is
87  called. At the end, set_is_optimizing(false) is called.
88 
89  \note Do not override; override do_set_is_optimizing() instead.
90  */
91  virtual void set_is_optimizing(bool);
92 
93  Optimizer* get_optimizer() const {
94  IMP_INTERNAL_CHECK(optimizer_,
95  "Must call set_optimizer before get_optimizer on state");
96  return optimizer_.get();
97  }
98 
99  //! Set the periodicity of this state.
100  /** This causes update() to invoke do_update() only every p calls
101  to update() rather than on every call (p=1). Note that this
102  periodicity is shared by all optimizers that own this
103  OptimizerState object.
104 
105  @param p periodicity
106  */
107  void set_period(unsigned int p);
108 
109  //! Get the periodicity of this state.
110  /** @return the periodicity of this state (how many calls to update()
111  are required to invoke do_update())
112  */
113  unsigned int get_period() const { return period_; }
114 
115  //! Reset counters, as if at the start of an optimize run.
116  virtual void reset();
117 
118  //! Force the state to perform its action now, ignoring the periodicity.
119  void update_always();
120 
121  //! Return the number of times do_update() has been called
122  unsigned int get_number_of_updates() const { return update_number_; }
123 
124  //! Set the counter of number of times do_update() has been called
125  void set_number_of_updates(unsigned int n) { update_number_ = n; }
126 
128 
129  protected:
130  /** This method is called every get_period() update calls. The number of
131  times this method has been called since the last reset or start of the
132  optimization run is passed.*/
133  virtual void do_update(unsigned int) { update(); }
134 
135  virtual void do_set_is_optimizing(bool) {}
136 
137  virtual ModelObjectsTemp do_get_inputs() const override {
138  return ModelObjectsTemp();
139  }
140  virtual ModelObjectsTemp do_get_outputs() const override IMP_SWIG_FINAL {
141  return ModelObjectsTemp();
142  }
143 
144  private:
146  bool is_optimizing_;
147 };
148 
149 IMPKERNEL_END_NAMESPACE
150 
151 #endif /* IMPKERNEL_OPTIMIZER_STATE_H */
unsigned int get_period() const
Get the periodicity of this state.
virtual void do_update(unsigned int)
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Set up destructor for a ref counted object.
A weak pointer to an Object or RefCountedObject.
Definition: WeakPointer.h:33
A more IMP-like version of the std::vector.
Definition: Vector.h:42
#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:89
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
virtual ModelObjectsTemp do_get_outputs() const override
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:28
Base class for all optimizers.
Definition: Optimizer.h:48
A weak pointer to an Object or RefCountedObject.
Base class for objects in a Model that depend on other objects.
virtual ModelObjectsTemp do_get_inputs() const override
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.
#define IMP_SWIG_FINAL
Have the compiler report an error if anything overrides this method.
unsigned int get_number_of_updates() const
Return the number of times do_update() has been called.