IMP logo
IMP Reference Guide  2.18.0
The Integrative Modeling Platform
Simulator.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Simulator.h
3  * \brief Base class for "simulators", such as molecular dynamics.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPATOM_SIMULATOR_H
10 #define IMPATOM_SIMULATOR_H
11 
12 #include <IMP/atom/atom_config.h>
13 
14 #include <IMP/Particle.h>
15 #include <IMP/Optimizer.h>
16 #include <IMP/internal/units.h>
17 #include <IMP/algebra/Vector3D.h>
18 
19 IMPATOM_BEGIN_NAMESPACE
20 
21 // for swig
22 class SimulationParameters;
23 
24 //! The base class for simulators.
25 /**
26  A simulator is an optimizer with dynamic tracking of time,
27  such that each frame is associated with a (possibly variable size)
28  time step.
29 
30  The simulation can be invoked directly by calling simulate(fs) for
31  a given time in femtoseconds, or by calling Optimizer::optimize(nf)
32  for a given number of frames.
33  */
34 class IMPATOMEXPORT Simulator : public Optimizer {
35  public:
36  /**
37  @param m model associated with simulator
38  @param name simulator name where %1% is a joker
39  @param wave_factor if >=1.001, use wave time step size with larger maximal
40  time step, using simulate_wave() when calling optimize()
41 
42  @note wave_factor is an advanced feature - if you're not sure, just use its
43  default, see also simulate_wave()
44  @note wave_factor is experimental and liable to change at any time.
45 
46  \see simulate()
47  */
48  Simulator(Model *m, std::string name = "Simulator %1%",
49  double wave_factor = 1.0);
50 
51  //! Simulate for a given time in fs
52  /**
53  simulate for at least the passed time, by calling do_simulate()
54  with optimizing states turned on
55 
56  @param time_in_fs time in femtoseconds
57  */
58  double simulate(double time_in_fs);
59 
60  //! Simulate for a given time in fs using a wave step function
61  //! with maximal time step increased by up to max_time_step_factor
62  /**
63  simulate for at least the passed time, by calling do_simulate_wave()
64  with optimizing states turned on
65 
66  @param time_in_fs time_in_fs in femtoseconds
67  @param max_time_step_factor the maximal factor by which the
68  maximum time step is exceeded
69  @param base base by which time step increases or decreases
70  during the wave
71 
72  @note This function is experimental and liable to change at any
73  time.
74  */
75  double simulate_wave(double time_in_fs, double max_time_step_factor = 10.0,
76  double base = 1.5);
77 
78  //! Return the simulator temperature in kelvin
79  double get_temperature() const { return temperature_; }
80 
81  //! Set the temperature of the simulator to d in kelvin units
82  /**
83  Sets the temperature of the simulator. Note that some simulators
84  (e.g. BrownianDynamics) may rely on other temperature-dependent
85  constants (e.g. diffusion coefficients via Diffusion decorator)
86  that will need to be updated independently to reflect the new
87  temperature.
88 
89  @param d temperature in K
90  */
91  void set_temperature(double d) { temperature_ = d; }
92 
93  /** \name Time steps
94  The simulator has a maximum allowed time step. It can take
95  shorter ones if needed due to stability concerns.
96 
97  As with all times in \imp, the time step is in fs.
98  @{
99  */
100  void set_maximum_time_step(double ts) { max_time_step_ = ts; }
101 
102  //! Get the maximum allowed time step in fs
103  double get_maximum_time_step() const { return max_time_step_; }
104 
105  //! Get the time of the last simulated time step (or the maximal time step
106  //! if the simulation has not started), in units of fs
107  double get_last_time_step() const {
108  if (last_time_step_ < 0)
109  return get_maximum_time_step();
110  else
111  return last_time_step_;
112  }
113 /** @} */
114 #ifndef IMP_DOXYGEN
115  void set_time_step(double ts) { set_maximum_time_step(ts); }
116 #endif
117 
118  // returns kt in units of kCal/mol for temperature get_temperature() [K]
119  double get_kt() const;
120 
121  /**
122  returns the simulation time in femtoseconds that was performed
123  by this simulator since it was constructed
124  @note this time can be tweaked using set_current_time() )
125  */
126  double get_current_time() const { return current_time_; }
127 
128  //! Sets the current simulation time in femtoseconds to ct.
129  void set_current_time(double ct) { current_time_ = ct; }
130 
131  //! Returns the set of particles used in the simulation.
132  /** If a non-empty
133  set of particles was provided explicitly by earlier calls to the
134  particles list accessor methods, eg, add_particles(), this set
135  it returned. Otherwise, the associated Model object is
136  searched for appropriate particles that have a mass and XYZ
137  decorators.
138 
139  \see add_particle()
140  \see add_particles()
141  \see remove_particle()
142  \see clear_particles()
143  \see set_particles()
144  \see set_particles_order()
145  */
146  ParticlesTemp get_simulation_particles() const;
147 
148  /**
149  Same as get_simulation_particles(), but returns particle
150  model indexes.
151 
152  \see get_simulation_particles()
153  */
154  ParticleIndexes get_simulation_particle_indexes() const;
155 
156  /** \name Explicitly accessing the particles list
157 
158  One can explicitly specify which particles should be used for
159  the simulation, or retrieve information about the list of particles.
160  Each particle must be a Mass and core::XYZ particle. If none are
161  specified, the model is searched for appropriate particles, based
162  on the get_simulation_particles() method, which can be overridden
163  by child classes.
164  @{
165  */
166  IMP_LIST(public, Particle, particle, Particle *, Particles);
167 
168  protected:
169  /** @} */
170  virtual Float do_optimize(unsigned int max_steps) override IMP_SWIG_FINAL;
171 
172  /** Perform any setup operations needed before running a series
173  of simulation steps
174 
175  @note Called by do_simulate() or do_simulate_wave() before iterative
176  calls to do_step()
177 */
178  virtual void setup(const ParticleIndexes &) {};
179 
180  //! Perform a single time step
181  /** \param[in] sc the particles that should be moved
182  \param[in] dt maximum time step value
183  \return the amount that time should be advanced.
184  */
185  virtual double do_step(const ParticleIndexes &sc, double dt) = 0;
186 
187  //! Return true if the passed particle is appropriate for the simulation.
188  virtual bool get_is_simulation_particle(ParticleIndex p) const = 0;
189 
190  /** called by simulate() -
191  calls setup() and then calls do_step() iteratively
192  till given simulation time is completed
193 
194  @param time time to simulate
195 
196  @return score at end of simulation period
197  */
198  virtual double do_simulate(double time);
199 
200  /** Calls the protected method setup() and then calls
201  method do_step() iteratively, and using a self adjusting time
202  step that can grow up to max_time_step_factor times than
203  the default time step returned by get_maximum_time_step()
204 
205  \see simulate_wave()
206  */
207  virtual double do_simulate_wave(double time_in_fs, double max_time_step_factor = 10.0,
208  double base = 1.5);
209 
210  private:
211  double temperature_;
212  double max_time_step_;
213  double current_time_;
214  double last_time_step_;
215  double wave_factor_; // if >1.0, use simulate_wave() from do_optimize()
216 };
217 
219 
220 
221 IMPATOM_END_NAMESPACE
222 
223 #endif /* IMPATOM_SIMULATOR_H */
double get_kt(double T)
Return kT for a given temperature in units of [kcal/mol].
The base class for simulators.
Definition: Simulator.h:34
double get_current_time() const
Definition: Simulator.h:126
void set_temperature(double d)
Set the temperature of the simulator to d in kelvin units.
Definition: Simulator.h:91
double get_maximum_time_step() const
Get the maximum allowed time step in fs.
Definition: Simulator.h:103
Base class for all optimizers.
#define IMP_LIST(protection, Ucname, lcname, Data, PluralData)
A macro to provide a uniform interface for storing lists of objects.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
virtual void setup(const ParticleIndexes &)
Definition: Simulator.h:178
virtual double do_optimize(unsigned int ns)=0
override this function to do actual optimization
void set_current_time(double ct)
Sets the current simulation time in femtoseconds to ct.
Definition: Simulator.h:129
Base class for all optimizers.
Definition: Optimizer.h:46
double get_last_time_step() const
Definition: Simulator.h:107
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
double get_temperature() const
Return the simulator temperature in kelvin.
Definition: Simulator.h:79
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:19
Simple 3D vector class.
Class to handle individual particles of a Model object.
Definition: Particle.h:41
#define IMP_SWIG_FINAL
Have the compiler report an error if anything overrides this method.