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