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