IMP logo
IMP Reference Guide  2.14.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 Monte Carlo optimization.
4  *
5  * Copyright 2007-2020 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/Model.h>
16 #include <IMP/particle_index.h>
17 #include <IMP/tuple_macros.h>
18 
19 IMPCORE_BEGIN_NAMESPACE
20 
21 //! Return value of the MonteCarloMover::propose() function.
22 /** 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  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. Most commonly this is a Monte Carlo
34  evaluation scheme.
35 
36  All changed attributes should be optimizable; it is undefined behavior to
37  try to optimize an attribute which is not.
38 
39  The output particles (ModelObject::do_get_outputs()) are assumed
40  to be equal to the inputs (ModelObject::do_get_inputs()).
41  */
42 class IMPCOREEXPORT MonteCarloMover : public ModelObject {
43  unsigned int num_proposed_;
44  unsigned int num_rejected_;
45  bool has_move_;
46 
47  public:
48  MonteCarloMover(Model *m, std::string name);
49 
50  //! Propose a modification
51  /** The method should return the list of all particles that were
52  actually moved and the ratio between the backward move probability
53  and the forward move probability (for Metropolis-Hastings moves).
54  Just return 1.0 for this value if you are not sure.
55  */
59  !has_move_,
60  "Mover already had proposed a move. "
61  << " This probably means you added it twice: " << get_name());
62  has_move_ = true;
63  set_was_used(true);
64  ++num_proposed_;
65  return do_propose();
66  }
67 
68  //! Roll back any changes made to the Particles
69  void reject() {
71  ++num_rejected_;
72  has_move_ = false;
73  do_reject();
74  }
75 
76  //! Accept/commit any changes made to the Particles
77  void accept() {
79  has_move_ = false;
80  do_accept();
81  }
82 
83  /** \name Statistics
84  Movers keep track of some statistics as they are used.
85  @{
86  */
87  unsigned int get_number_of_proposed() const { return num_proposed_; }
88  unsigned int get_number_of_accepted() const {
89  return num_proposed_ - num_rejected_;
90  }
91  void reset_statistics() {
92  num_proposed_ = 0;
93  num_rejected_ = 0;
94  }
95  /** @} */
96  protected:
97  //! Implement propose_move()
98  virtual MonteCarloMoverResult do_propose() = 0;
99  //! Implement reset_proposed_move()
100  virtual void do_reject() = 0;
101  //! Implement accept_proposed_move(); default implementation is empty
102  virtual void do_accept() {}
103 
105  return get_inputs();
106  }
107 };
108 
110 
111 IMPCORE_END_NAMESPACE
112 
113 #endif /* IMPCORE_MONTE_CARLO_MOVER_H */
Various general useful functions for IMP.
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:284
Storage of a model, its restraints, constraints and particles.
virtual ModelObjectsTemp do_get_outputs() const
Return value of the MonteCarloMover::propose() function.
Various general useful macros for IMP.
A more IMP-like version of the std::vector.
Definition: Vector.h:39
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
A base class for classes which perturb particles.
void accept()
Accept/commit any changes made to the Particles.
void reject()
Roll back any changes made to the Particles.
Single variable function.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
ModelObjectsTemp get_inputs() const
IMP::Vector< MonteCarloMoverResult > MonteCarloMoverResults
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
void set_was_used(bool tf) const
MonteCarloMoverResult propose()
Propose a modification.