IMP logo
IMP Reference Guide  develop.7cb8855c60,2024/10/08
The Integrative Modeling Platform
IMP::atom::Simulator Class Referenceabstract

The base class for simulators. More...

#include <IMP/atom/Simulator.h>

+ Inheritance diagram for IMP::atom::Simulator:

Detailed Description

The base class for simulators.

A simulator is an optimizer with dynamic tracking of time, such that each frame is associated with a (possibly variable size) time step.

The simulation can be invoked directly by calling simulate(fs) for a given time in femtoseconds, or by calling Optimizer::optimize(nf) for a given number of frames.

Definition at line 34 of file Simulator.h.

Public Member Functions

 Simulator (Model *m, std::string name="Simulator %1%", double wave_factor=1.0)
 
double get_current_time () const
 
double get_kt () const
 
ParticleIndexes get_simulation_particle_indexes () const
 
ParticlesTemp get_simulation_particles () const
 Returns the set of particles used in the simulation. More...
 
double get_temperature () const
 Return the simulator temperature in kelvin. More...
 
void set_current_time (double ct)
 Sets the current simulation time in femtoseconds to ct. More...
 
void set_temperature (double d)
 Set the temperature of the simulator to d in kelvin units. More...
 
double simulate (double time_in_fs)
 Simulate for a given time in fs. More...
 
double simulate_wave (double time_in_fs, double max_time_step_factor=10.0, double base=1.5)
 
- 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
 
virtual VersionInfo get_version_info () const
 Get information about the module and version of the object. More...
 
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)
 
virtual std::string get_type_name () const
 

Protected Member Functions

virtual Float do_optimize (unsigned int max_steps) override
 override this function to do actual optimization More...
 
virtual double do_simulate (double time)
 
virtual double do_simulate_wave (double time_in_fs, double max_time_step_factor=10.0, double base=1.5)
 
virtual double do_step (const ParticleIndexes &sc, double dt)=0
 Perform a single time step. More...
 
virtual bool get_is_simulation_particle (ParticleIndex p) const =0
 Return true if the passed particle is appropriate for the simulation. More...
 
virtual void setup (const ParticleIndexes &)
 
- 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 ()
 

Time steps

The simulator has a maximum allowed time step. It can take shorter ones if needed due to stability concerns.

As with all times in IMP, the time step is in fs.

void set_maximum_time_step (double ts)
 
double get_maximum_time_step () const
 Get the maximum allowed time step in fs. More...
 
double get_last_time_step () const
 

Explicitly accessing the particles list

One can explicitly specify which particles should be used for the simulation, or retrieve information about the list of particles. Each particle must be a Mass and core::XYZ particle. If none are specified, the model is searched for appropriate particles, based on the get_simulation_particles() method, which can be overridden by child classes.

list particles
 A Python list of Particles More...
 
void remove_particle (Particle *d)
 
void remove_particles (const Particles &d)
 
void set_particles (const Particles &ps)
 
void set_particles_order (const Particles &objs)
 
unsigned int add_particle (Particle *obj)
 
void add_particles (const Particles &objs)
 
void clear_particles ()
 
unsigned int get_number_of_particles () const
 
bool get_has_particles ()
 
Particleget_particle (unsigned int i) const
 
Particles get_particles () const
 
void erase_particle (unsigned int i)
 
void reserve_particles (unsigned int sz)
 

Constructor & Destructor Documentation

IMP::atom::Simulator::Simulator ( Model m,
std::string  name = "Simulator %1%",
double  wave_factor = 1.0 
)
Parameters
mmodel associated with simulator
namesimulator name where %1% is a joker
wave_factorif >=1.001, use wave time step size with larger maximal time step, using simulate_wave() when calling optimize()
Note
wave_factor is an advanced feature - if you're not sure, just use its default, see also simulate_wave()
wave_factor is experimental and liable to change at any time.
See Also
simulate()

Member Function Documentation

virtual Float IMP::atom::Simulator::do_optimize ( unsigned int  ns)
overrideprotectedvirtual

override this function to do actual optimization

Implements IMP::Optimizer.

virtual double IMP::atom::Simulator::do_simulate ( double  time)
protectedvirtual

called by simulate() - calls setup() and then calls do_step() iteratively till given simulation time is completed

Parameters
timetime to simulate
Returns
score at end of simulation period
virtual double IMP::atom::Simulator::do_simulate_wave ( double  time_in_fs,
double  max_time_step_factor = 10.0,
double  base = 1.5 
)
protectedvirtual

Calls the protected method setup() and then calls method do_step() iteratively, and using a self adjusting time step that can grow up to max_time_step_factor times than the default time step returned by get_maximum_time_step()

See Also
simulate_wave()
virtual double IMP::atom::Simulator::do_step ( const ParticleIndexes sc,
double  dt 
)
protectedpure virtual

Perform a single time step.

Parameters
[in]scthe particles that should be moved
[in]dtmaximum time step value
Returns
the amount that time should be advanced.

Implemented in IMP::atom::MolecularDynamics, IMP::atom::BrownianDynamics, and IMP::spb::MolecularDynamicsWithWte.

double IMP::atom::Simulator::get_current_time ( ) const

returns the simulation time in femtoseconds that was performed by this simulator since it was constructed

Note
this time can be tweaked using set_current_time() )

Definition at line 126 of file Simulator.h.

virtual bool IMP::atom::Simulator::get_is_simulation_particle ( ParticleIndex  p) const
protectedpure virtual

Return true if the passed particle is appropriate for the simulation.

Implemented in IMP::atom::MolecularDynamics, IMP::atom::BrownianDynamics, IMP::spb::MolecularDynamicsWithWte, and IMP::isd::MolecularDynamics.

double IMP::atom::Simulator::get_last_time_step ( ) const

Get the time of the last simulated time step (or the maximal time step if the simulation has not started), in units of fs

Definition at line 107 of file Simulator.h.

double IMP::atom::Simulator::get_maximum_time_step ( ) const

Get the maximum allowed time step in fs.

Definition at line 103 of file Simulator.h.

ParticleIndexes IMP::atom::Simulator::get_simulation_particle_indexes ( ) const

Same as get_simulation_particles(), but returns particle model indexes.

See Also
get_simulation_particles()
ParticlesTemp IMP::atom::Simulator::get_simulation_particles ( ) const

Returns the set of particles used in the simulation.

If a non-empty set of particles was provided explicitly by earlier calls to the particles list accessor methods, eg, add_particles(), this set it returned. Otherwise, the associated Model object is searched for appropriate particles that have a mass and XYZ decorators.

See Also
add_particle()
add_particles()
remove_particle()
clear_particles()
set_particles()
set_particles_order()
double IMP::atom::Simulator::get_temperature ( ) const

Return the simulator temperature in kelvin.

Definition at line 79 of file Simulator.h.

void IMP::atom::Simulator::set_current_time ( double  ct)

Sets the current simulation time in femtoseconds to ct.

Definition at line 129 of file Simulator.h.

void IMP::atom::Simulator::set_temperature ( double  d)

Set the temperature of the simulator to d in kelvin units.

Sets the temperature of the simulator. Note that some simulators (e.g. BrownianDynamics) may rely on other temperature-dependent constants (e.g. diffusion coefficients via Diffusion decorator) that will need to be updated independently to reflect the new temperature.

Parameters
dtemperature in K

Definition at line 91 of file Simulator.h.

virtual void IMP::atom::Simulator::setup ( const ParticleIndexes )
protectedvirtual

Perform any setup operations needed before running a series of simulation steps

Note
Called by do_simulate() or do_simulate_wave() before iterative calls to do_step()

Reimplemented in IMP::atom::MolecularDynamics, IMP::atom::BrownianDynamics, and IMP::spb::MolecularDynamicsWithWte.

Definition at line 178 of file Simulator.h.

double IMP::atom::Simulator::simulate ( double  time_in_fs)

Simulate for a given time in fs.

simulate for at least the passed time, by calling do_simulate() with optimizing states turned on

Parameters
time_in_fstime in femtoseconds
double IMP::atom::Simulator::simulate_wave ( double  time_in_fs,
double  max_time_step_factor = 10.0,
double  base = 1.5 
)

Simulate for a given time in fs using a wave step function with maximal time step increased by up to max_time_step_factor simulate for at least the passed time, by calling do_simulate_wave() with optimizing states turned on

Parameters
time_in_fstime_in_fs in femtoseconds
max_time_step_factorthe maximal factor by which the maximum time step is exceeded
basebase by which time step increases or decreases during the wave
Note
This function is experimental and liable to change at any time.

Member Data Documentation

list IMP::atom::Simulator::particles

A Python list of Particles

Note
This class member is only available in Python.

Definition at line 166 of file Simulator.h.


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