IMP logo
IMP Reference Guide  develop.5651aa123e,2024/07/21
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-2023 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 #include <cereal/access.hpp>
19 #include <cereal/types/base_class.hpp>
20 
21 IMPCORE_BEGIN_NAMESPACE
22 
23 //! Return value of the MonteCarloMover::propose() function.
24 /** The values are the list of
25  particle indexes moved and the ratio between the probability of
26  the backwards move and the probability of the forwards move (for
27  many or most move sets this is 1.0).
28 */
29 IMP_NAMED_TUPLE_2(MonteCarloMoverResult, MonteCarloMoverResults,
30  ParticleIndexes, moved_particles, double,
31  proposal_ratio, );
32 
33 //! A base class for classes which perturb particles.
34 /** Mover objects propose a move, which can then be either accepted or rejected
35  based on some criteria. Most commonly this is a Monte Carlo
36  evaluation scheme.
37 
38  All changed attributes should be optimizable; it is undefined behavior to
39  try to optimize an attribute which is not.
40 
41  The output particles (ModelObject::do_get_outputs()) are assumed
42  to be equal to the inputs (ModelObject::do_get_inputs()).
43  */
44 class IMPCOREEXPORT MonteCarloMover : public ModelObject {
45  unsigned int num_proposed_;
46  unsigned int num_rejected_;
47  bool has_move_;
48 
49  friend class cereal::access;
50 
51  template<class Archive> void serialize(Archive &ar) {
52  ar(cereal::base_class<ModelObject>(this),
53  num_proposed_, num_rejected_, has_move_);
54  }
55 
56  public:
57  MonteCarloMover(Model *m, std::string name);
59 
60  //! Propose a modification
61  /** The method should return the list of all particles that were
62  actually moved and the ratio between the backward move probability
63  and the forward move probability (for Metropolis-Hastings moves).
64  Just return 1.0 for this value if you are not sure.
65  */
69  !has_move_,
70  "Mover already had proposed a move. "
71  << " This probably means you added it twice: " << get_name());
72  has_move_ = true;
73  set_was_used(true);
74  ++num_proposed_;
75  return do_propose();
76  }
77 
78  //! Roll back any changes made to the Particles
79  void reject() {
81  ++num_rejected_;
82  has_move_ = false;
83  do_reject();
84  }
85 
86  //! Accept/commit any changes made to the Particles
87  void accept() {
89  has_move_ = false;
90  do_accept();
91  }
92 
93  /** \name Statistics
94  Movers keep track of some statistics as they are used.
95  @{
96  */
97  unsigned int get_number_of_proposed() const { return num_proposed_; }
98  unsigned int get_number_of_accepted() const {
99  return num_proposed_ - num_rejected_;
100  }
101  void reset_statistics() {
102  num_proposed_ = 0;
103  num_rejected_ = 0;
104  }
105  /** @} */
106  protected:
107  //! Implement propose_move()
108  virtual MonteCarloMoverResult do_propose() = 0;
109  //! Implement reset_proposed_move()
110  virtual void do_reject() = 0;
111  //! Implement accept_proposed_move(); default implementation is empty
112  virtual void do_accept() {}
113 
114  virtual ModelObjectsTemp do_get_outputs() const override {
115  return get_inputs();
116  }
117 };
118 
120 
121 IMPCORE_END_NAMESPACE
122 
123 #endif /* IMPCORE_MONTE_CARLO_MOVER_H */
Functions and adaptors for dealing with particle indexes.
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.
Return value of the MonteCarloMover::propose() function.
Macros to help in defining tuple classes.
A more IMP-like version of the std::vector.
Definition: Vector.h:50
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:28
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.
Base class for objects in a Model that depend on other objects.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
virtual ModelObjectsTemp do_get_outputs() const override
#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
void set_was_used(bool tf) const
MonteCarloMoverResult propose()
Propose a modification.