IMP logo
IMP Reference Guide  develop.42a12322a9,2023/03/24
The Integrative Modeling Platform
IMP::core::MonteCarlo Class Reference

A Monte Carlo optimizer. More...

#include <IMP/core/MonteCarlo.h>

+ Inheritance diagram for IMP::core::MonteCarlo:

Detailed Description

A Monte Carlo optimizer.

The optimizer uses a set of Mover objects to propose steps. At each sampling iteration, all Movers added to MonteCarlo are called to generate a new proposed configuration.

The movers propose some modification, which is then accepted or rejected based on the Metropolis criterion. Optionally, a number of local optimization steps are taken before the MonteCarlo step is accepted or rejected.

If you want to sequentially call one mover at every iteration, wrap all movers into a SerialMover first, and then add the SerialMover to MonteCarlo.

By default, the lowest score state encountered is returned.

See Also

Definition at line 45 of file MonteCarlo.h.

Public Member Functions

 MonteCarlo (Model *m)
double get_best_accepted_energy () const
 If return best is on, returns the best energy found so far. More...
IncrementalScoringFunctionget_incremental_scoring_function () const
double get_last_accepted_energy () const
 Return the energy of the last accepted state. More...
double get_maximum_difference () const
double get_score_threshold () const
 Get the score threshold. More...
virtual std::string get_type_name () const override
bool get_use_incremental_scoring_function () const
virtual ::IMP::VersionInfo get_version_info () const override
 Get information about the module and version of the object. More...
void set_incremental_scoring_function (IncrementalScoringFunction *isf)
void set_maximum_difference (double d)
void set_return_best (bool tf)
void set_score_moved (bool mv)
 If set true (default false), only rescore moved particles. More...
void set_score_threshold (double s)
 Set the score threshold. More...
- Public Member Functions inherited from IMP::Optimizer
 Optimizer (Model *m, std::string name="Optimizer %1%")
double get_last_score () const
 Return the score found in the last evaluate. More...
ScoringFunctionget_scoring_function () const
 Return the scoring function that is being used. More...
bool get_stop_on_good_score () const
double optimize (unsigned int max_steps)
 Optimize the model for up to max_steps iterations. More...
virtual void set_scoring_function (ScoringFunctionAdaptor sf)
 Set the scoring function to use. More...
void set_stop_on_good_score (bool tf)
void remove_optimizer_state (OptimizerState *d)
void remove_optimizer_states (const OptimizerStates &d)
void set_optimizer_states (const OptimizerStates &ps)
void set_optimizer_states_order (const OptimizerStates &objs)
unsigned int add_optimizer_state (OptimizerState *obj)
void add_optimizer_states (const OptimizerStates &objs)
void clear_optimizer_states ()
unsigned int get_number_of_optimizer_states () const
bool get_has_optimizer_states ()
OptimizerStateget_optimizer_state (unsigned int i) const
OptimizerStates get_optimizer_states () const
void erase_optimizer_state (unsigned int i)
void reserve_optimizer_states (unsigned int sz)
- Public Member Functions inherited from IMP::ModelObject
 ModelObject (Model *m, std::string name)
bool get_has_dependencies () const
 Return whether this object has dependencies computed. More...
bool get_has_required_score_states () const
 Return whether score states are computed. More...
ModelObjectsTemp get_inputs () const
ModelObjectsTemps get_interactions () const
 Get the interacting sets induced by this ModelObject. More...
Modelget_model () const
ModelObjectsTemp get_outputs () const
const ScoreStatesTempget_required_score_states () const
 Get the score states that are ancestors of this in the dependency graph. More...
void set_has_dependencies (bool tf)
 Either invalidate the dependencies or ensure they are correct. More...
void set_has_required_score_states (bool tf)
 Compute the required score states. More...
- Public Member Functions inherited from IMP::Object
virtual void clear_caches ()
CheckLevel get_check_level () const
LogLevel get_log_level () const
void set_check_level (CheckLevel l)
void set_log_level (LogLevel l)
 Set the logging level used in this object. More...
void set_was_used (bool tf) const
void show (std::ostream &out=std::cout) const
const std::string & get_name () const
void set_name (std::string name)

Protected Member Functions

bool do_accept_or_reject_move (double score, double last, const MonteCarloMoverResult &moved)
bool do_accept_or_reject_move (double score, const MonteCarloMoverResult &moved)
virtual double do_evaluate (const ParticleIndexes &moved, bool force_full_score) const
 Get the current energy. More...
MonteCarloMoverResult do_move ()
virtual Float do_optimize (unsigned int max_steps) override
 override this function to do actual optimization More...
virtual void do_step ()
 a class that inherits from this should override this method More...
ParticleIndexes get_movable_particles () const
- Protected Member Functions inherited from IMP::Optimizer
virtual ModelObjectsTemp do_get_inputs () const override
virtual ModelObjectsTemp do_get_outputs () const override
 don't return anything here to avoid pointless dependencies More...
ModelObjectsTemp get_optimizer_state_inputs () const
void update_states () const
 Update optimizer states, should be called at each successful step. More...
- Protected Member Functions inherited from IMP::ModelObject
virtual ModelObjectsTemps do_get_interactions () const
virtual void handle_set_has_required_score_states (bool)
- Protected Member Functions inherited from IMP::Object
 Object (std::string name)
 Construct an object with the given name. More...
virtual void do_destroy ()

Protected Attributes

ParticleIndexes reset_pis_


The kT value has to be on the same scale as the differences in energy between good and bad states (and so the default is likely to not be a good choice).

void set_kt (Float t)
Float get_kt () const


unsigned int get_number_of_downward_steps () const
 Return how many times the optimizer has stepped to lower score. More...
unsigned int get_number_of_upward_steps () const
 Return how many times the optimizer has stepped to higher score. More...
unsigned int get_number_of_proposed_steps () const
 Get number of proposed moves. More...
unsigned int get_number_of_accepted_steps () const
 Get number of accepted moves. More...
void reset_statistics ()


The following methods are used to manipulate the list of Movers. Each mover is called at each optimization step, giving it a chance to change the current configuration.

list movers
 A Python list of Movers More...
void remove_mover (MonteCarloMover *d)
void remove_movers (const MonteCarloMovers &d)
void set_movers (const MonteCarloMovers &ps)
void set_movers_order (const MonteCarloMovers &objs)
unsigned int add_mover (MonteCarloMover *obj)
void add_movers (const MonteCarloMovers &objs)
void clear_movers ()
unsigned int get_number_of_movers () const
bool get_has_movers ()
MonteCarloMoverget_mover (unsigned int i) const
MonteCarloMovers get_movers () const
void erase_mover (unsigned int i)
void reserve_movers (unsigned int sz)

Member Function Documentation

bool IMP::core::MonteCarlo::do_accept_or_reject_move ( double  score,
double  last,
const MonteCarloMoverResult moved 

Note that if return best is true, this will save the current state of the model. Also, if the move is accepted, the optimizer states will be updated.

virtual double IMP::core::MonteCarlo::do_evaluate ( const ParticleIndexes moved,
bool  force_full_score 
) const

Get the current energy.

By default it just calls Optimizer::get_scoring_function()->evaluate(false). However, if an incremental scoring function is used, the list of moved particles will be used to evaluate the score more efficiently. Also, if there is a maximum allowed difference in scores Optimizer::get_scoring_function()->evaluate_if_below() will be called instead, allowing more efficient evaluation. Classes which override this method should be similarly aware for efficiency.

The list of moved particles is passed.

Reimplemented in IMP::isd::HybridMonteCarlo.

Definition at line 197 of file MonteCarlo.h.

+ Here is the call graph for this function:

virtual Float IMP::core::MonteCarlo::do_optimize ( unsigned int  ns)

override this function to do actual optimization

Implements IMP::Optimizer.

virtual void IMP::core::MonteCarlo::do_step ( )

a class that inherits from this should override this method

Reimplemented in IMP::core::MonteCarloWithBasinHopping, IMP::core::MonteCarloWithLocalOptimization, IMP::spb::MonteCarloWithWte, and IMP::isd::HybridMonteCarlo.

double IMP::core::MonteCarlo::get_best_accepted_energy ( ) const

If return best is on, returns the best energy found so far.

Definition at line 92 of file MonteCarlo.h.

double IMP::core::MonteCarlo::get_last_accepted_energy ( ) const

Return the energy of the last accepted state.

Definition at line 89 of file MonteCarlo.h.

ParticleIndexes IMP::core::MonteCarlo::get_movable_particles ( ) const

Get all movable particles (those that can be moved by the current movers.

unsigned int IMP::core::MonteCarlo::get_number_of_accepted_steps ( ) const

Get number of accepted moves.

Definition at line 114 of file MonteCarlo.h.

unsigned int IMP::core::MonteCarlo::get_number_of_downward_steps ( ) const

Return how many times the optimizer has stepped to lower score.

Definition at line 101 of file MonteCarlo.h.

unsigned int IMP::core::MonteCarlo::get_number_of_proposed_steps ( ) const

Get number of proposed moves.

Definition at line 109 of file MonteCarlo.h.

unsigned int IMP::core::MonteCarlo::get_number_of_upward_steps ( ) const

Return how many times the optimizer has stepped to higher score.

Definition at line 105 of file MonteCarlo.h.

double IMP::core::MonteCarlo::get_score_threshold ( ) const

Get the score threshold.

Definition at line 130 of file MonteCarlo.h.

virtual ::IMP::VersionInfo IMP::core::MonteCarlo::get_version_info ( ) const

Get information about the module and version of the object.

Reimplemented from IMP::Object.

Reimplemented in IMP::core::MonteCarloWithBasinHopping, IMP::core::MonteCarloWithLocalOptimization, IMP::spb::MonteCarloWithWte, and IMP::isd::HybridMonteCarlo.

Definition at line 52 of file MonteCarlo.h.

void IMP::core::MonteCarlo::set_incremental_scoring_function ( IncrementalScoringFunction isf)

Set whether to use incremental evaluate or evaluate all restraints each time. This cannot be changed during optimization.

As of IMP release 2.17. See the IMP Deprecation Policy for more information about deprecation in IMP. Use set_score_moved() instead
void IMP::core::MonteCarlo::set_maximum_difference ( double  d)

Computations can be accelerated by throwing out the tails of the distribution of accepted moves. To do this, specify a maximum acceptable difference between the before and after scores.

Definition at line 137 of file MonteCarlo.h.

void IMP::core::MonteCarlo::set_return_best ( bool  tf)

By default, the optimizer returns the lowest scoring state found so far. If, instead, you wish to return the last accepted state, set return best to false.

Definition at line 58 of file MonteCarlo.h.

void IMP::core::MonteCarlo::set_score_moved ( bool  mv)

If set true (default false), only rescore moved particles.

By default, on each move the score of the entire system is calculated. If it is guaranteed that only Movers and ScoreStates move the system, then the score can potentially be calculated more quickly by caching the scores on parts of the system that don't move. This is still experimental.

See Also
Some MonteCarlo subclasses do local optimization after each move, which can move more particles than the Movers touched. In this case the guarantee does not hold and this optimization should probably not be used.

Definition at line 74 of file MonteCarlo.h.

void IMP::core::MonteCarlo::set_score_threshold ( double  s)

Set the score threshold.

Definition at line 127 of file MonteCarlo.h.

Member Data Documentation

list IMP::core::MonteCarlo::movers

A Python list of Movers

This class member is only available in Python.

Definition at line 148 of file MonteCarlo.h.

The documentation for this class was generated from the following file: