IMP  2.4.0
The Integrative Modeling Platform
MonteCarloMover.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/MonteCarloMover.h
3  * \brief The base class for movers for MC optimization.
4  *
5  * Copyright 2007-2015 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPCORE_MONTE_CARLO_MOVER_H
10 #define IMPCORE_MONTE_CARLO_MOVER_H
11 
12 #include <IMP/core/core_config.h>
13 
14 #include <IMP/ModelObject.h>
15 #include <IMP/kernel/Model.h>
16 #include <IMP/particle_index.h>
17 #include <IMP/base/tuple_macros.h>
18 
19 IMPCORE_BEGIN_NAMESPACE
20 
21 /** The MonteCarloMoverResult is used as the return value for the
22  MonteCarloMover::propose() function. The values are the list of
23  particle (indexes) moved and the ratio between the probability of
24  the backwards move and the probability of the forwards move (for
25  many or most move sets this is 1.0).
26 */
27 IMP_NAMED_TUPLE_2(MonteCarloMoverResult, MonteCarloMoverResults,
28  kernel::ParticleIndexes, moved_particles, double,
29  proposal_ratio, );
30 
31 //! A base class for classes which perturb particles.
32 /** Mover objects propose a move, which can then be either accepted or rejected
33  based on some criteria. For example, in a Monte-Carlo evaluation scheme.
34 
35  All changed attributes should be optimizable, it is undefined behavior to
36  try to optimize an attribute which is not.
37 
38  The output particles (kernel::ModelObject::do_get_outputs()) are assumed
39  to be equal to the inputs (kernel::ModelObject::do_get_inputs()).
40  */
41 class IMPCOREEXPORT MonteCarloMover : public kernel::ModelObject {
42  unsigned int num_proposed_;
43  unsigned int num_rejected_;
44  bool has_move_;
45 
46  public:
47  MonteCarloMover(kernel::Model *m, std::string name);
48 
49  //! propose a modification
50  /** The method should return the list of all particles that were
51  actually moved and the ratio between the backward move probability
52  and the forward move probability (for Metropolis-Hastings moves).
53  Just return 1.0 for this value if you are not sure.
54  */
58  !has_move_,
59  "Mover already had proposed a move. "
60  << " This probably means you added it twice: " << get_name());
61  has_move_ = true;
62  set_was_used(true);
63  ++num_proposed_;
64  return do_propose();
65  }
66 
67  //! Roll back any changes made to the kernel::Particles
68  void reject() {
70  ++num_rejected_;
71  has_move_ = false;
72  do_reject();
73  }
74 
75  //! Roll back any changes made to the kernel::Particles
76  void accept() {
78  has_move_ = false;
79  do_accept();
80  }
81 
82  /** \name Statistics
83  Movers keep track of some statistics as they are used.
84  @{
85  */
86  unsigned int get_number_of_proposed() const { return num_proposed_; }
87  unsigned int get_number_of_accepted() const {
88  return num_proposed_ - num_rejected_;
89  }
90  void reset_statistics() {
91  num_proposed_ = 0;
92  num_rejected_ = 0;
93  }
94  /** @} */
95  protected:
96  //! Implement propose_move()
97  virtual MonteCarloMoverResult do_propose() = 0;
98  //! Implement reset_proposed_move()
99  virtual void do_reject() = 0;
100  //! Implement accept_proposed_move(), default implementation is empty
101  virtual void do_accept() {}
102 
104  return get_inputs();
105  }
106 };
107 
109 
110 IMPCORE_END_NAMESPACE
111 
112 #endif /* IMPCORE_MONTE_CARLO_MOVER_H */
virtual kernel::ModelObjectsTemp do_get_outputs() const
IMP::base::Vector< MonteCarloMoverResult > MonteCarloMoverResults
ModelObjectsTemp get_inputs() const
Import IMP/kernel/particle_index.h in the namespace.
void set_was_used(bool tf) const
virtual void do_accept()
Implement accept_proposed_move(), default implementation is empty.
#define IMP_OBJECT_LOG
Set the log level to the object's log level.
Definition: log_macros.h:297
Various general useful macros for IMP.
A base class for classes which perturb particles.
void accept()
Roll back any changes made to the kernel::Particles.
void reject()
Roll back any changes made to the kernel::Particles.
Storage of a model, its restraints, constraints and particles.
Import IMP/kernel/ModelObject.h in the namespace.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing sets of objects.
Definition: object_macros.h:52
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:170
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:73
MonteCarloMoverResult propose()
propose a modification