IMP logo
IMP Reference Guide  2.11.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-2019 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 
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 optimizable
42  parameters of the Particles contained in the Model.
43 
44  \see Sampler
45 */
46 class IMPKERNELEXPORT Optimizer : public ModelObject {
47  mutable Floats widths_;
48  Pointer<Model> my_model_;
49  bool stop_on_good_score_;
50  Pointer<ScoringFunction> scoring_function_;
51 
52  static void set_optimizer_state_optimizer(OptimizerState *os, Optimizer *o);
53 
54  protected:
55 #ifndef IMP_DOXYGEN
56  void set_is_optimizing_states(bool tf) const;
57 #endif
58  ModelObjectsTemp get_optimizer_state_inputs() const;
60  return get_optimizer_state_inputs();
61  }
62  //! don't return anything here to avoid pointless dependencies
63  virtual ModelObjectsTemp do_get_outputs() const { return ModelObjectsTemp(); }
64 
65  public:
66  Optimizer(Model *m, std::string name = "Optimizer %1%");
67 
68  //! Optimize the model for up to max_steps iterations
69  /** Optimize the model
70 
71  @param[in] max_steps The maximum number of iterations of the
72  optimizer to perform. Increasing this number will generally make
73  the optimizer spend more time searching for a solution, but
74  beyond that, the details of what changes will vary.
75 
76  @return The final score.
77  */
78  double optimize(unsigned int max_steps);
79 
80  /** Optimization can be stopped if all the thresholds in the Model are
81  satisfied. */
82  void set_stop_on_good_score(bool tf) { stop_on_good_score_ = tf; }
83  bool get_stop_on_good_score() const { return stop_on_good_score_; }
84  //! Return the score found in the last evaluate
85  double get_last_score() const { return scoring_function_->get_last_score(); }
86 
87  //! Return the scoring function that is being used
88  /** \throws ValueException if no scoring function was set
89  */
91  if (scoring_function_) {
92  return scoring_function_;
93  } else {
94  IMP_THROW("No scoring function was set. "
95  "Use Optimizer::set_scoring_function() to set one.",
97  }
98  }
99 
100  /** @name States
101 
102  The stored OptimizerState objects are updated each time the
103  Optimizer decides to accept a new configuration of the Model.
104  To manipulate the list of optimizer states use the methods below.
105  */
106  /**@{*/
107  IMP_LIST_ACTION(public, OptimizerState, OptimizerStates, optimizer_state,
108  optimizer_states, OptimizerState *, OptimizerStates,
109  set_optimizer_state_optimizer(obj, this);
110  , {},
111  { Optimizer::set_optimizer_state_optimizer(obj, nullptr); });
112  /**@}*/
113 
114  //! Set the scoring function to use.
115  virtual void set_scoring_function(ScoringFunctionAdaptor sf);
116 
118 
119  // swig needs this at the end for some reason I don't understand
120  protected:
121  //! override this function to do actual optimization
122  virtual double do_optimize(unsigned int ns) = 0;
123  //! Update optimizer states, should be called at each successful step
124  /** Make sure the scoring function restraints are up to date before this is
125  called (eg by calling evaluate).*/
126  void update_states() const;
127 };
128 
130 
131 IMPKERNEL_END_NAMESPACE
132 
133 #endif /* IMPKERNEL_OPTIMIZER_H */
virtual ModelObjectsTemp do_get_outputs() const
don't return anything here to avoid pointless dependencies
Definition: Optimizer.h:63
Basic types used by IMP.
Storage of a model, its restraints, constraints and particles.
virtual ModelObjectsTemp do_get_inputs() const
Definition: Optimizer.h:59
A smart pointer to a reference counted object.
Definition: Pointer.h:87
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 class for storing lists of IMP items.
For backwards compatibility.
Single variable function.
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)
Shared optimizer state.
void set_stop_on_good_score(bool tf)
Definition: Optimizer.h:82
double get_last_score() const
Return the score found in the last evaluate.
Definition: Optimizer.h:85
An exception for an invalid value being passed to IMP.
Definition: exception.h:137
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
ScoringFunction * get_scoring_function() const
Return the scoring function that is being used.
Definition: Optimizer.h:90