IMP  2.1.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-2013 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  double min_score_;
48  bool stop_on_good_score_;
49  mutable base::Pointer<ScoringFunction> cache_;
50  base::Pointer<ScoringFunction> scoring_function_;
51 
52  static void set_optimizer_state_optimizer(OptimizerState *os, Optimizer *o);
53  virtual void do_set_model(kernel::Model *m) IMP_OVERRIDE { my_model_ = m; }
54 
55  protected:
56 #ifndef IMP_DOXYGEN
57  void set_is_optimizing_states(bool tf) const;
58 #endif
59  ModelObjectsTemp get_optimizer_state_inputs() const;
60  virtual ModelObjectsTemp do_get_inputs() const IMP_OVERRIDE {
61  return get_optimizer_state_inputs();
62  }
63  //! don't return anything here to avoid pointless dependencies
64  virtual ModelObjectsTemp do_get_outputs() const { return ModelObjectsTemp(); }
65 
66  public:
67  Optimizer(kernel::Model *m, std::string name = "Optimizer %1%");
68 
69  //! Optimize the model for up to max_steps iterations
70  /** Optimize the model
71 
72  @param[in] max_steps The maximum number of iterations of the
73  optimizer to perform. Increasing this number will generally make
74  the optimizer spend more time searching for a solution, but
75  beyond that, the details of what changes will vary.
76 
77  @return The final score.
78  */
79  double optimize(unsigned int max_steps);
80 
81  /** Optimization can be stopped if all the thresholds in the Model are
82  satisfied. */
83  void set_stop_on_good_score(bool tf) { stop_on_good_score_ = tf; }
84  bool get_stop_on_good_score() const { return stop_on_good_score_; }
85  //! Return the score found in the last evaluate
86  double get_last_score() const { return cache_->get_last_score(); }
87 
88  //! Return the scoring function that is being used
90  if (scoring_function_)
91  return scoring_function_;
92  else if (cache_)
93  return cache_;
94  else
95  return cache_ = get_model()->create_model_scoring_function();
96  }
97 
98  /** @name States
99 
100  The stored OptimizerState objects are updated each time the
101  Optimizer decides to accept a new configuration of the Model.
102  To manipulate the list of optimizer states use the methods below.
103  */
104  /**@{*/
105  IMP_LIST_ACTION(public, OptimizerState, OptimizerStates, optimizer_state,
106  optimizer_states, OptimizerState *, OptimizerStates,
107  set_optimizer_state_optimizer(obj, this);
108  , {},
109  { Optimizer::set_optimizer_state_optimizer(obj, nullptr); });
110  /**@}*/
111 
112  /** By default, the Optimizer uses the scoring function provided by
113  the model, but you can use another scoring function instead.
114  */
115  virtual void set_scoring_function(ScoringFunctionAdaptor sf);
116 
118 
119 ///////////////////////// DEPRECATED METHODS
120 
121 #ifndef SWIG
122  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
123  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
124  FloatIndexes get_optimized_attributes() const;
125  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
126  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
127  void set_value(FloatIndex fi, double v) const;
128  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
129  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
130  Float get_value(FloatIndex fi) const;
131  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
132  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
133  Float get_derivative(FloatIndex fi) const;
134 #if !defined(SWIG)
135  /** \deprecated_at{2.1} Use AttributeOptimizer instead.*/
136  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
137  double width(FloatKey k) const;
138 #endif
139  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
140  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
141  double get_width(FloatKey k) const;
142  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
143  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
144  void set_scaled_value(FloatIndex fi, Float v) const;
145  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
146  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
147  double get_scaled_value(FloatIndex fi) const;
148  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
149  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
150  double get_scaled_derivative(FloatIndex fi) const;
151  /** \deprecated_at{2.1} Use AttributeOptimizer instead. */
152  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
153  void clear_range_cache();
154 #endif // SWIG
155  /** \deprecated_at{2.1} Use Optimizer::get_scoring_function() instead. */
156  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
157  Restraints get_restraints() const;
158  /** \deprecated_at{2.1} Use the constructor with a Model and a name.*/
159  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
160  Optimizer();
161  /** \deprecated_at{2.1} Do not use as it is not reliably supported. */
162  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
163  void set_score_threshold(double s);
164  /** \deprecated_at{2.1} Do not use as it is not reliably supported. */
165  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
166  double get_score_threshold() const;
167  /** \deprecated_at{2.1} Use set_scoring_function() instead. */
168  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
169  void set_restraints(const RestraintsTemp &rs);
170 
171  // swig needs this at the end for some reason I don't understand
172  protected:
173  //! override this function to do actual optimization
174  virtual double do_optimize(unsigned int ns) = 0;
175  //! Update optimizer states, should be called at each successful step
176  /** Make sure the scoring function restraints are up to date before this is
177  called (eg by calling evaluate).*/
178  void update_states() const;
179 };
180 
182 
183 IMPKERNEL_END_NAMESPACE
184 
185 #endif /* IMPKERNEL_OPTIMIZER_H */
void set_stop_on_good_score(bool tf)
virtual ModelObjectsTemp do_get_outputs() const
don&#39;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.
IMP::base::Vector< IMP::base::WeakPointer< Restraint > > RestraintsTemp
IMP::base::Vector< IMP::base::Pointer< Restraint > > Restraints
A smart pointer to a reference counted object.
Definition: base/Pointer.h:87
IMP::kernel::Optimizer Optimizer
kernel::RestraintsTemp get_restraints(const Subset &s, const ParticleStatesTable *pst, const DependencyGraph &dg, kernel::RestraintSet *rs)
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.
virtual void do_set_model(kernel::Model *)
For backwards compatibility.
double Float
Basic floating-point value (could be float, double...)
Definition: base/types.h:20
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.
IMP::kernel::FloatIndex FloatIndex
Key< 0, true > FloatKey
The type used to identify float attributes in the Particles.
Class for storing model, its restraints, constraints, and particles.
IMP::kernel::FloatIndexes FloatIndexes