IMP  2.2.0
The Integrative Modeling Platform
MonteCarlo.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/MonteCarlo.h \brief Simple Monte Carlo optimizer.
3  *
4  * Copyright 2007-2014 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPCORE_MONTE_CARLO_H
9 #define IMPCORE_MONTE_CARLO_H
10 
11 #include <IMP/core/core_config.h>
12 #include "MonteCarloMover.h"
14 #include <IMP/Optimizer.h>
15 #include <IMP/container_macros.h>
16 #include <IMP/kernel/internal/container_helpers.h>
18 #include <IMP/Configuration.h>
19 
20 #include <boost/random/uniform_real.hpp>
21 
22 IMPCORE_BEGIN_NAMESPACE
23 
24 /** Allow code to test for the changes in MC interface.*/
25 #define IMP_CORE_HAS_MONTE_CARLO_MOVER 1
26 
27 //! A Monte Carlo optimizer.
28 /** The optimizer uses a set of Mover objects to propose steps. At
29  each sampling iteration, all Movers added to MonteCarlo are called to
30  generate a new proposed configuration.
31 
32  The movers propose some modification, which is then accepted or
33  rejected based on the Metropolis criterion. Optionally, a number
34  of local optimization steps are taken before the MonteCarlo step
35  is accepted or rejected.
36 
37  If you want to sequentially call one mover at every iteration, wrap
38  all movers into a SerialMover first, and then add the SerialMover to
39  MonteCarlo.
40 
41  By default, the lowest score state encountered is returned.
42 
43  \see Mover
44  */
45 class IMPCOREEXPORT MonteCarlo : public Optimizer {
46  public:
48 
49  protected:
50  virtual Float do_optimize(unsigned int max_steps);
52  public:
53  /** By default, the optimizer returns the lowest score state
54  found so far. If, instead, you wish to return the last accepted
55  state, set return best to false.
56  */
57  void set_return_best(bool tf) { return_best_ = tf; }
58 
59  /** \name kT
60  The kT value has to be on the same scale as the differences
61  in energy between good and bad states (and so the default is
62  likely to not be a good choice).
63  @{
64  */
65  void set_kt(Float t) {
66  IMP_INTERNAL_CHECK(t > 0, "Temperature must be positive");
67  temp_ = t;
68  }
69  Float get_kt() const { return temp_; }
70  /** @} */
71  /** Return the energy of last accepted state.
72  */
73  double get_last_accepted_energy() const { return last_energy_; }
74 
75  /** If return best is on, you can get the best energy
76  found so far.*/
77  double get_best_accepted_energy() const {
78  IMP_USAGE_CHECK(return_best_, "Getting the best energy"
79  << " requires return best being on.");
80  return best_energy_;
81  }
82  /** \name Statistics
83  @{
84  */
85  //! Return how many times the optimizer has succeeded in taking a step
86  /** \deprecated_at{2.2} Use get_number_of_accepted_steps() instead
87  */
88  IMPCORE_DEPRECATED_FUNCTION_DECL(2.2)
89  unsigned int get_number_of_forward_steps() const {
90  IMPCORE_DEPRECATED_FUNCTION_DEF(2.2,
91  "Use get_number_of_accepted_steps() instead.");
92  return get_number_of_accepted_steps();
93  }
94 
95  //! Return how many times the optimizer has stepped to lower score
96  unsigned int get_number_of_downward_steps() const {
97  return stat_downward_steps_taken_;
98  }
99  //! Return how many times the optimizer has stepped to higher score
100  unsigned int get_number_of_upward_steps() const {
101  return stat_upward_steps_taken_;
102  }
103  //! Get number of proposed moves
104  unsigned int get_number_of_proposed_steps() const {
105  return stat_downward_steps_taken_ + stat_upward_steps_taken_ +
106  stat_num_failures_;
107  }
108  //! Get number of accepted moves
109  unsigned int get_number_of_accepted_steps() const {
110  return stat_downward_steps_taken_ + stat_upward_steps_taken_;
111  }
112  void reset_statistics() {
113  stat_downward_steps_taken_ = 0;
114  stat_upward_steps_taken_ = 0;
115  stat_num_failures_ = 0;
116  }
117 
118  /** @} */
119 
120  //! Set the score threshold.
121  //* An optimization is terminated if the score drops below this value. */
122  void set_score_threshold(double s) { min_score_ = s; }
123 
124  //! Get the score threshold.
125  double get_score_threshold() const { return min_score_; }
126 
127  /** Computations can be accelerated by throwing out
128  the tails of the distribution of accepted moves. To
129  do this, specific a maximum acceptable difference
130  between the before and after scores.
131  */
132  void set_maximum_difference(double d) { max_difference_ = d; }
133 
134  double get_maximum_difference() const { return max_difference_; }
135  /** @name Movers
136 
137  The following methods are used to manipulate the list of Movers.
138  Each mover is called at each optimization step, giving it a chance
139  to change the current configuration.
140  @{
141  */
142  IMP_LIST_ACTION(public, Mover, Movers, mover, movers, MonteCarloMover *,
143  MonteCarloMovers, {}, {}, {});
144  /** @} */
145 
146  /** \name Incremental
147  Efficient evaluation of non-bonded list based restraints is
148  a bit tricky with incremental evaluation.
149  @{
150  */
151  /** Set whether to use incremental evaluate or evaluate all restraints
152  each time. This cannot be changed during optimization.
153  */
154  void set_incremental_scoring_function(IncrementalScoringFunction *isf);
155  bool get_use_incremental_scoring_function() const { return isf_; }
156  IncrementalScoringFunction *get_incremental_scoring_function() const {
157  return isf_;
158  }
159  /** @} */
160  protected:
161  /** Get all movable particles (those that can be moved by the current
162  movers.*/
163  kernel::ParticleIndexes get_movable_particles() const;
164  /** Note that if return best is true, this will save the current
165  state of the model. Also, if the move is accepted, the
166  optimizer states will be updated.
167  */
168  bool do_accept_or_reject_move(double score, double last,
169  double proposal_ratio);
170  bool do_accept_or_reject_move(double score, double proposal_ratio) {
171  return do_accept_or_reject_move(score, get_last_accepted_energy(),
172  proposal_ratio);
173  }
174 
175  MonteCarloMoverResult do_move();
176  //! a class that inherits from this should override this method
177  virtual void do_step();
178  //! Get the current energy
179  /** By default it just calls
180  Optimizer::get_scoring_function()->evaluate(false). However,
181  if an incremental scoring function is used, the list of moved
182  particles will be used to evaluate the score more efficiently.
183  Also, if there is a maximum allowed difference in scores
184  Optimizer::get_scoring_function()->evaluate_if_below()
185  will be called instead, allowing more efficient evaluation.
186  Classes which override this method should be similarly aware for
187  efficiency.
188 
189  The list of moved particles is passed.
190  */
191  virtual double do_evaluate(const kernel::ParticleIndexes &moved) const {
192  IMP_UNUSED(moved);
193  if (isf_) {
194  isf_->set_moved_particles(moved);
195  }
196  if (get_maximum_difference() < NO_MAX) {
197  return get_scoring_function()->evaluate_if_below(
198  false, last_energy_ + max_difference_);
199  } else {
200  return get_scoring_function()->evaluate(false);
201  }
202  }
203 
204  private:
205  double temp_;
206  double last_energy_;
207  double best_energy_;
208  double max_difference_;
209  unsigned int stat_downward_steps_taken_;
210  unsigned int stat_upward_steps_taken_;
211  unsigned int stat_num_failures_;
212  bool return_best_;
213  double min_score_;
215  ::boost::uniform_real<> rand_;
216 
218 };
219 
220 //! This variant of Monte Carlo that relaxes after each move
221 class IMPCOREEXPORT MonteCarloWithLocalOptimization : public MonteCarlo {
223  unsigned int num_local_;
224 
225  public:
226  MonteCarloWithLocalOptimization(Optimizer *opt, unsigned int steps);
227 
228  unsigned int get_number_of_steps() const { return num_local_; }
229 
230  Optimizer *get_local_optimizer() const { return opt_; }
231 
232  protected:
233  virtual void do_step() IMP_OVERRIDE;
235 };
236 
237 //! This variant of Monte Carlo uses basis hopping
238 /** Basin hopping is where, after a move, a local optimizer is used to relax
239  the model before the energy computation. However, the pre-relaxation state
240  of the model is used as the starting point for the next step. The idea
241  is that models are accepted or rejected based on the score of the nearest
242  local minima, but they can still climb the barriers in between as the model
243  is not reset to the minima after each step.
244  */
245 class IMPCOREEXPORT MonteCarloWithBasinHopping
247  public:
248  MonteCarloWithBasinHopping(Optimizer *opt, unsigned int ns);
249 
250  protected:
251  virtual void do_step() IMP_OVERRIDE;
253 };
254 
255 IMPCORE_END_NAMESPACE
256 
257 #endif /* IMPCORE_MONTE_CARLO_H */
double get_kt(double T)
A Monte Carlo optimizer.
Definition: MonteCarlo.h:45
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
unsigned int get_number_of_upward_steps() const
Return how many times the optimizer has stepped to higher score.
Definition: MonteCarlo.h:100
Simple Monte Carlo optimizer.
double get_score_threshold() const
Get the score threshold.
Definition: MonteCarlo.h:125
double evaluate(bool derivatives)
Evaluate and return the score.
A smart pointer to a ref-counted Object that is a class memeber.
Definition: base/Pointer.h:147
void set_maximum_difference(double d)
Definition: MonteCarlo.h:132
double get_last_accepted_energy() const
Definition: MonteCarlo.h:73
#define IMP_UNUSED(variable)
A smart pointer to a reference counted object.
Definition: base/Pointer.h:87
IMP::base::Vector< IMP::base::Pointer< MonteCarloMover > > MonteCarloMovers
Import IMP/kernel/Optimizer.h in the namespace.
void set_score_threshold(double s)
Set the score threshold.
Definition: MonteCarlo.h:122
Import IMP/kernel/container_macros.h in the namespace.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
virtual void do_step()
a class that inherits from this should override this method
This variant of Monte Carlo uses basis hopping.
Definition: MonteCarlo.h:245
unsigned int get_number_of_downward_steps() const
Return how many times the optimizer has stepped to lower score.
Definition: MonteCarlo.h:96
#define IMP_INTERNAL_CHECK(expr, message)
An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown.
The base class for movers for MC optimization.
unsigned int get_number_of_accepted_steps() const
Get number of accepted moves.
Definition: MonteCarlo.h:109
This variant of Monte Carlo that relaxes after each move.
Definition: MonteCarlo.h:221
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
double get_best_accepted_energy() const
Definition: MonteCarlo.h:77
Base class for all optimizers.
virtual double do_evaluate(const kernel::ParticleIndexes &moved) const
Get the current energy.
Definition: MonteCarlo.h:191
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.
virtual double do_optimize(unsigned int ns)=0
override this function to do actual optimization
virtual void do_step()
a class that inherits from this should override this method
Import IMP/kernel/Configuration.h in the namespace.
Functions to generate vectors.
unsigned int get_number_of_proposed_steps() const
Get number of proposed moves.
Definition: MonteCarlo.h:104
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:72