IMP logo
IMP Reference Guide  2.16.0
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-2021 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 
63  //! don't return anything here to avoid pointless dependencies
65  return ModelObjectsTemp();
66  }
67 
68  public:
69  Optimizer(Model *m, std::string name = "Optimizer %1%");
70 
71  //! Optimize the model for up to max_steps iterations
72  /** Optimize the model
73 
74  @param[in] max_steps The maximum number of iterations of the
75  optimizer to perform. Increasing this number will generally make
76  the optimizer spend more time searching for a solution, but
77  beyond that, the details of what changes will vary.
78 
79  @return The final score.
80  */
81  double optimize(unsigned int max_steps);
82 
83  /** Optimization can be stopped if all the thresholds in the Model are
84  satisfied. */
85  void set_stop_on_good_score(bool tf) { stop_on_good_score_ = tf; }
86  bool get_stop_on_good_score() const { return stop_on_good_score_; }
87  //! Return the score found in the last evaluate
88  double get_last_score() const { return scoring_function_->get_last_score(); }
89 
90  //! Return the scoring function that is being used
91  /** \throws ValueException if no scoring function was set
92  */
94  if (scoring_function_) {
95  return scoring_function_;
96  } else {
97  IMP_THROW("No scoring function was set. "
98  "Use Optimizer::set_scoring_function() to set one.",
100  }
101  }
102 
103  /** @name States
104 
105  The stored OptimizerState objects are updated each time the
106  Optimizer decides to accept a new configuration of the Model.
107  To manipulate the list of optimizer states use the methods below.
108  */
109  /**@{*/
110  IMP_LIST_ACTION(public, OptimizerState, OptimizerStates, optimizer_state,
111  optimizer_states, OptimizerState *, OptimizerStates,
112  set_optimizer_state_optimizer(obj, this);
113  , {},
114  { Optimizer::set_optimizer_state_optimizer(obj, nullptr); });
115  /**@}*/
116 
117  //! Set the scoring function to use.
118  virtual void set_scoring_function(ScoringFunctionAdaptor sf);
119 
121 
122  // swig needs this at the end for some reason I don't understand
123  protected:
124  //! override this function to do actual optimization
125  virtual double do_optimize(unsigned int ns) = 0;
126  //! Update optimizer states, should be called at each successful step
127  /** Make sure the scoring function restraints are up to date before this is
128  called (eg by calling evaluate).*/
129  void update_states() const;
130 };
131 
133 
134 IMPKERNEL_END_NAMESPACE
135 
136 #endif /* IMPKERNEL_OPTIMIZER_H */
virtual ModelObjectsTemp do_get_outputs() const
don't return anything here to avoid pointless dependencies
Definition: Optimizer.h:64
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:89
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:26
Base class for all optimizers.
Definition: Optimizer.h:46
A class for storing lists of IMP items.
For backwards compatibility.
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)
Shared optimizer state.
void set_stop_on_good_score(bool tf)
Definition: Optimizer.h:85
double get_last_score() const
Return the score found in the last evaluate.
Definition: Optimizer.h:88
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:93