IMP logo
IMP Reference Guide  2.20.1
The Integrative Modeling Platform
Optimizer.h
Go to the documentation of this file.
1 /**
2  * \file IMP/Optimizer.h \brief Base class for all optimizers.
3  *
4  * Copyright 2007-2022 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPKERNEL_OPTIMIZER_H
9 #define IMPKERNEL_OPTIMIZER_H
10 
11 #include <IMP/kernel_config.h>
12 #include "base_types.h"
13 #include <IMP/Object.h>
14 #include "utility.h"
15 #include "Model.h"
16 #include "Particle.h"
17 #include "ModelObject.h"
18 #include <IMP/Pointer.h>
19 #include "OptimizerState.h"
20 #include <IMP/Vector.h>
21 #include <limits>
22 #include <cmath>
23 #include <cereal/access.hpp>
24 #include <cereal/types/base_class.hpp>
25 
26 IMPKERNEL_BEGIN_NAMESPACE
27 
28 //! Base class for all optimizers.
29 /** An optimizer attempts to improve the current configuration of the
30  Model by moving particles around so as to lower the score.
31 
32  The Optimizer maintains a list of OptimizerStates which are
33  updated each time the conformation is changed.
34 
35  The optimizers have one key method Optimizer::optimize() which takes
36  the number of steps to perform. The optimizers can have other
37  stopping conditions as appropriate.
38 
39  A typical optimization loop proceeds by:
40  - the optimizer calls Model::evaluate() to compute the score
41  (and possibly the derivatives) of the
42  current conformation of the Model.
43  - the optimizer uses this information to update the optimizable
44  parameters of the Particles contained in the Model.
45 
46  \see Sampler
47 */
48 class IMPKERNELEXPORT Optimizer : public ModelObject {
49  bool stop_on_good_score_;
50  Pointer<ScoringFunction> scoring_function_;
51 
52  friend class cereal::access;
53 
54  template<class Archive> void serialize(Archive &ar) {
55  ar(cereal::base_class<ModelObject>(this), stop_on_good_score_,
56  scoring_function_, mutable_access_optimizer_states());
57  if (std::is_base_of<cereal::detail::InputArchiveBase, Archive>::value) {
58  for (auto &obj : mutable_access_optimizer_states()) {
59  set_optimizer_state_optimizer(obj, this);
60  }
61  }
62  }
63 
64  static void set_optimizer_state_optimizer(OptimizerState *os, Optimizer *o);
65 
66  protected:
67 #ifndef IMP_DOXYGEN
68  void set_is_optimizing_states(bool tf) const;
69 #endif
70  ModelObjectsTemp get_optimizer_state_inputs() const;
71  virtual ModelObjectsTemp do_get_inputs() const override {
72  return get_optimizer_state_inputs();
73  }
74 
75  //! don't return anything here to avoid pointless dependencies
76  virtual ModelObjectsTemp do_get_outputs() const override {
77  return ModelObjectsTemp();
78  }
79 
80  public:
81  Optimizer(Model *m, std::string name = "Optimizer %1%");
82  Optimizer() {}
83 
84  //! Optimize the model for up to max_steps iterations
85  /** Optimize the model
86 
87  @param[in] max_steps The maximum number of iterations of the
88  optimizer to perform. Increasing this number will generally make
89  the optimizer spend more time searching for a solution, but
90  beyond that, the details of what changes will vary.
91 
92  @return The final score.
93  */
94  double optimize(unsigned int max_steps);
95 
96  /** Optimization can be stopped if all the thresholds in the Model are
97  satisfied. */
98  void set_stop_on_good_score(bool tf) { stop_on_good_score_ = tf; }
99  bool get_stop_on_good_score() const { return stop_on_good_score_; }
100  //! Return the score found in the last evaluate
101  double get_last_score() const { return scoring_function_->get_last_score(); }
102 
103  //! Return the scoring function that is being used
104  /** \throws ValueException if no scoring function was set
105  */
107  if (scoring_function_) {
108  return scoring_function_;
109  } else {
110  IMP_THROW("No scoring function was set. "
111  "Use Optimizer::set_scoring_function() to set one.",
113  }
114  }
115 
116  /** @name States
117 
118  The stored OptimizerState objects are updated each time the
119  Optimizer decides to accept a new configuration of the Model.
120  To manipulate the list of optimizer states use the methods below.
121  */
122  /**@{*/
123  IMP_LIST_ACTION(public, OptimizerState, OptimizerStates, optimizer_state,
124  optimizer_states, OptimizerState *, OptimizerStates,
125  set_optimizer_state_optimizer(obj, this);
126  , {},
127  { Optimizer::set_optimizer_state_optimizer(obj, nullptr); });
128  /**@}*/
129 
130  //! Set the scoring function to use.
131  virtual void set_scoring_function(ScoringFunctionAdaptor sf);
132 
134 
135  // swig needs this at the end for some reason I don't understand
136  protected:
137  //! override this function to do actual optimization
138  virtual double do_optimize(unsigned int ns) = 0;
139  //! Update optimizer states, should be called at each successful step
140  /** Make sure the scoring function restraints are up to date before this is
141  called (eg by calling evaluate).*/
142  void update_states() const;
143 };
144 
146 
147 IMPKERNEL_END_NAMESPACE
148 
149 #endif /* IMPKERNEL_OPTIMIZER_H */
Basic types used by IMP.
Storage of a model, its restraints, constraints and particles.
A more IMP-like version of the std::vector.
Definition: Vector.h:42
A smart pointer to a reference counted object.
Definition: Pointer.h:87
IMP::Vector< IMP::WeakPointer< ModelObject > > ModelObjectsTemp
Definition: base_types.h:106
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
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
virtual ModelObjectsTemp do_get_outputs() const override
don't return anything here to avoid pointless dependencies
Definition: Optimizer.h:76
A class for storing lists of IMP items.
Various general useful functions for IMP.
Base class for objects in a Model that depend on other objects.
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
#define IMP_THROW(message, exception_name)
Throw an exception with a message.
Definition: check_macros.h:50
A nullptr-initialized pointer to an IMP Object.
Represents a scoring function on the model.
A shared base class to help in debugging and things.
Shared optimizer state that is invoked upon commitment of new coordinates.
#define IMP_REF_COUNTED_NONTRIVIAL_DESTRUCTOR(Name)
virtual ModelObjectsTemp do_get_inputs() const override
Definition: Optimizer.h:71
Shared optimizer state.
void set_stop_on_good_score(bool tf)
Definition: Optimizer.h:98
double get_last_score() const
Return the score found in the last evaluate.
Definition: Optimizer.h:101
An exception for an invalid value being passed to IMP.
Definition: exception.h:136
ScoringFunction * get_scoring_function() const
Return the scoring function that is being used.
Definition: Optimizer.h:106