IMP logo
IMP Reference Guide  develop.6100cc8943,2021/10/26
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-2021 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/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:
47  MonteCarlo(Model *m);
48 
49  protected:
50  ParticleIndexes reset_pis_;
51  virtual Float do_optimize(unsigned int max_steps) IMP_OVERRIDE;
53  public:
54  /** By default, the optimizer returns the lowest scoring state
55  found so far. If, instead, you wish to return the last accepted
56  state, set return best to false.
57  */
58  void set_return_best(bool tf) { return_best_ = tf; }
59 
60  //! If set true (default false), only rescore moved particles
61  /** By default, on each move the score of the entire system is
62  calculated. If it is guaranteed that only Movers and ScoreStates
63  move the system, then the score can potentially be calculated
64  more quickly by caching the scores on parts of the system that
65  don't move. This is still experimental.
66 
67  \note Some MonteCarlo subclasses do local optimization after each
68  move, which can move more particles than the Movers touched.
69  In this case the guarantee does not hold and this optimization
70  should probably not be used.
71  */
72  void set_score_moved(bool mv) { score_moved_ = mv; }
73 
74  /** \name kT
75  The kT value has to be on the same scale as the differences
76  in energy between good and bad states (and so the default is
77  likely to not be a good choice).
78  @{
79  */
80  void set_kt(Float t) {
81  IMP_INTERNAL_CHECK(t >= 0, "Temperature must not be negative");
82  temp_ = t;
83  }
84  Float get_kt() const { return temp_; }
85  /** @} */
86  //! Return the energy of the last accepted state.
87  double get_last_accepted_energy() const { return last_energy_; }
88 
89  //! If return best is on, returns the best energy found so far.
90  double get_best_accepted_energy() const {
91  IMP_USAGE_CHECK(return_best_, "Getting the best energy"
92  << " requires return best being on.");
93  return best_energy_;
94  }
95  /** \name Statistics
96  @{
97  */
98  //! Return how many times the optimizer has stepped to lower score
99  unsigned int get_number_of_downward_steps() const {
100  return stat_downward_steps_taken_;
101  }
102  //! Return how many times the optimizer has stepped to higher score
103  unsigned int get_number_of_upward_steps() const {
104  return stat_upward_steps_taken_;
105  }
106  //! Get number of proposed moves
107  unsigned int get_number_of_proposed_steps() const {
108  return stat_downward_steps_taken_ + stat_upward_steps_taken_ +
109  stat_num_failures_;
110  }
111  //! Get number of accepted moves
112  unsigned int get_number_of_accepted_steps() const {
113  return stat_downward_steps_taken_ + stat_upward_steps_taken_;
114  }
115  void reset_statistics() {
116  stat_downward_steps_taken_ = 0;
117  stat_upward_steps_taken_ = 0;
118  stat_num_failures_ = 0;
119  }
120 
121  /** @} */
122 
123  //! Set the score threshold.
124  //* An optimization is terminated if the score drops below this value. */
125  void set_score_threshold(double s) { min_score_ = s; }
126 
127  //! Get the score threshold.
128  double get_score_threshold() const { return min_score_; }
129 
130  /** Computations can be accelerated by throwing out
131  the tails of the distribution of accepted moves. To
132  do this, specify a maximum acceptable difference
133  between the before and after scores.
134  */
135  void set_maximum_difference(double d) { max_difference_ = d; }
136 
137  double get_maximum_difference() const { return max_difference_; }
138  /** @name Movers
139 
140  The following methods are used to manipulate the list of Movers.
141  Each mover is called at each optimization step, giving it a chance
142  to change the current configuration.
143  @{
144  */
145  IMP_LIST_ACTION(public, Mover, Movers, mover, movers, MonteCarloMover *,
146  MonteCarloMovers, {}, {}, {});
147  /** @} */
148 
149  /** \name Incremental
150  Efficient evaluation of non-bonded list based restraints is
151  a bit tricky with incremental evaluation.
152  @{
153  */
154  /** Set whether to use incremental evaluate or evaluate all restraints
155  each time. This cannot be changed during optimization.
156  */
157  void set_incremental_scoring_function(IncrementalScoringFunction *isf);
158  bool get_use_incremental_scoring_function() const { return isf_; }
159  IncrementalScoringFunction *get_incremental_scoring_function() const {
160  return isf_;
161  }
162  /** @} */
163  protected:
164  /** Get all movable particles (those that can be moved by the current
165  movers.*/
166  ParticleIndexes get_movable_particles() const;
167  /** Note that if return best is true, this will save the current
168  state of the model. Also, if the move is accepted, the
169  optimizer states will be updated.
170  */
171  bool do_accept_or_reject_move(double score, double last,
172  const MonteCarloMoverResult &moved);
173 
174  bool do_accept_or_reject_move(double score,
175  const MonteCarloMoverResult &moved) {
176  return do_accept_or_reject_move(score, get_last_accepted_energy(), moved);
177  }
178 
179  MonteCarloMoverResult do_move();
180  //! a class that inherits from this should override this method
181  virtual void do_step();
182  //! Get the current energy
183  /** By default it just calls
184  Optimizer::get_scoring_function()->evaluate(false). However,
185  if an incremental scoring function is used, the list of moved
186  particles will be used to evaluate the score more efficiently.
187  Also, if there is a maximum allowed difference in scores
188  Optimizer::get_scoring_function()->evaluate_if_below()
189  will be called instead, allowing more efficient evaluation.
190  Classes which override this method should be similarly aware for
191  efficiency.
192 
193  The list of moved particles is passed.
194  */
195  virtual double do_evaluate(const ParticleIndexes &moved,
196  bool force_full_score) const {
197  if (isf_) {
198  isf_->set_moved_particles(moved);
199  }
200  if (get_maximum_difference() < NO_MAX) {
201  if (score_moved_ && !force_full_score) {
202  return get_scoring_function()->evaluate_moved_if_below(
203  false, moved, reset_pis_, last_energy_ + max_difference_);
204  } else {
205  return get_scoring_function()->evaluate_if_below(
206  false, last_energy_ + max_difference_);
207  }
208  } else {
209  if (score_moved_ && !force_full_score) {
210  return get_scoring_function()->evaluate_moved(false, moved, reset_pis_);
211  } else {
212  return get_scoring_function()->evaluate(false);
213  }
214  }
215  }
216 
217  private:
218  double temp_;
219  double last_energy_;
220  double best_energy_;
221  double max_difference_;
222  unsigned int stat_downward_steps_taken_;
223  unsigned int stat_upward_steps_taken_;
224  unsigned int stat_num_failures_;
225  bool return_best_;
226  bool score_moved_;
227  double min_score_;
229  ::boost::uniform_real<> rand_;
230 
232 };
233 
234 //! This variant of Monte Carlo that relaxes after each move
235 class IMPCOREEXPORT MonteCarloWithLocalOptimization : public MonteCarlo {
237  unsigned int num_local_;
238 
239  public:
240  MonteCarloWithLocalOptimization(Optimizer *opt, unsigned int steps);
241 
242  unsigned int get_number_of_steps() const { return num_local_; }
243 
244  Optimizer *get_local_optimizer() const { return opt_; }
245 
246  protected:
247  virtual void do_step() IMP_OVERRIDE;
249 };
250 
251 //! This variant of Monte Carlo uses basis hopping
252 /** Basin hopping is where, after a move, a local optimizer is used to relax
253  the model before the energy computation. However, the pre-relaxation state
254  of the model is used as the starting point for the next step. The idea
255  is that models are accepted or rejected based on the score of the nearest
256  local minima, but they can still climb the barriers in between as the model
257  is not reset to the minima after each step.
258  */
259 class IMPCOREEXPORT MonteCarloWithBasinHopping
261  public:
262  MonteCarloWithBasinHopping(Optimizer *opt, unsigned int ns);
263 
264  protected:
265  virtual void do_step() IMP_OVERRIDE;
267 };
268 
269 IMPCORE_END_NAMESPACE
270 
271 #endif /* IMPCORE_MONTE_CARLO_H */
double get_kt(double T)
Return kT for a given temperature in units of [kcal/mol].
A Monte Carlo optimizer.
Definition: MonteCarlo.h:45
unsigned int get_number_of_upward_steps() const
Return how many times the optimizer has stepped to higher score.
Definition: MonteCarlo.h:103
Score model efficiently when a small number of particles are changed.
double get_score_threshold() const
Get the score threshold.
Definition: MonteCarlo.h:128
const double NO_MAX
Use this value when you want to turn off maximum for restraint evaluation.
IMP::Vector< IMP::Pointer< MonteCarloMover > > MonteCarloMovers
virtual double do_evaluate(const ParticleIndexes &moved, bool force_full_score) const
Get the current energy.
Definition: MonteCarlo.h:195
void set_maximum_difference(double d)
Definition: MonteCarlo.h:135
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
double get_last_accepted_energy() const
Return the energy of the last accepted state.
Definition: MonteCarlo.h:87
void set_score_moved(bool mv)
If set true (default false), only rescore moved particles.
Definition: MonteCarlo.h:72
Base class for all optimizers.
void set_score_threshold(double s)
Set the score threshold.
Definition: MonteCarlo.h:125
Macros to define containers of objects.
A smart pointer to a reference counted object.
Definition: Pointer.h:87
#define IMP_INTERNAL_CHECK(expr, message)
An assertion to check for internal errors in IMP. An IMP::ErrorException will be thrown.
Definition: check_macros.h:139
virtual void do_step()
a class that inherits from this should override this method
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
This variant of Monte Carlo uses basis hopping.
Definition: MonteCarlo.h:259
unsigned int get_number_of_downward_steps() const
Return how many times the optimizer has stepped to lower score.
Definition: MonteCarlo.h:99
virtual double do_optimize(unsigned int ns)=0
override this function to do actual optimization
Base class for all optimizers.
Definition: Optimizer.h:46
The base class for movers for Monte Carlo optimization.
unsigned int get_number_of_accepted_steps() const
Get number of accepted moves.
Definition: MonteCarlo.h:112
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:146
This variant of Monte Carlo that relaxes after each move.
Definition: MonteCarlo.h:235
double get_best_accepted_energy() const
If return best is on, returns the best energy found so far.
Definition: MonteCarlo.h:90
double evaluate_moved(bool derivatives, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis)
Score when some particles have moved.
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:20
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
virtual void do_step()
a class that inherits from this should override this method
Store a set of configurations of the model.
Functions to search over vectors.
double evaluate(bool derivatives)
Evaluate and return the score.
unsigned int get_number_of_proposed_steps() const
Get number of proposed moves.
Definition: MonteCarlo.h:107
#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