IMP logo
IMP Reference Guide  2.5.0
The Integrative Modeling Platform
Simulator.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Simulator.h
3  * \brief Simple molecular dynamics optimizer.
4  *
5  * Copyright 2007-2015 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  double get_temperature() const { return temperature_; }
79  void set_temperature(double d) { temperature_ = d; }
80  /** \name Time steps
81  The simulator has a maximum allowed time step. It can take
82  shorter ones if needed due to stability concerns.
83 
84  As with all times in \imp, the time step is in fs.
85  @{
86  */
87  void set_maximum_time_step(double ts) { max_time_step_ = ts; }
88  double get_maximum_time_step() const { return max_time_step_; }
89  double get_last_time_step() const {
90  if (last_time_step_ < 0)
91  return get_maximum_time_step();
92  else
93  return last_time_step_;
94  }
95 /** @} */
96 #ifndef IMP_DOXYGEN
97  void set_time_step(double ts) { set_maximum_time_step(ts); }
98 #endif
99 
100  double get_kt() const;
101 
102  /**
103  returns the simulation time in femtoseconds that was performed
104  by this simulator since it was constructed
105  @note this time can be tweaked using set_current_time() )
106  */
107  double get_current_time() const { return current_time_; }
108 
109  //! Sets the current simulation time in femtoseconds to ct.
110  void set_current_time(double ct) { current_time_ = ct; }
111 
112  //! Returns the set of particles used in the simulation.
113  /** If a non-empty
114  set of particles was provided explicitly by earlier calls to the
115  particles list accessor methods, eg, add_particles(), this set
116  it returned. Otherwise, the associated Model object is
117  searched for appropriate particles that have a mass and XYZ
118  decorators.
119 
120  \see add_particle()
121  \see add_particles()
122  \see remove_particle()
123  \see clear_particles()
124  \see set_particles()
125  \see set_particles_order()
126  */
127  ParticlesTemp get_simulation_particles() const;
128 
129  /**
130  Same as get_simulation_particles(), but returns particle
131  model indexes.
132 
133  \see get_simulation_particles()
134  */
135  ParticleIndexes get_simulation_particle_indexes() const;
136 
137  /** \name Explicitly accessing the particles list
138 
139  One can explicitly specify which particles should be used for
140  the simulation, or retrieve information about the list of particles.
141  Each particle must be a Mass and core::XYZ particle. If none are
142  specified, the model is searched for appropriate particles, based
143  on the get_simulation_particles() method, which can be overridden
144  by child classes.
145  @{
146  */
147  IMP_LIST(public, Particle, particle, Particle *, Particles);
148 
149  protected:
150  /** @} */
151  virtual Float do_optimize(unsigned int max_steps) IMP_OVERRIDE IMP_FINAL;
152 
153  /** Perform any setup operations needed before running a series
154  of simulation steps
155 
156  @note Called by do_simulate() or do_simulate_wave() before iterative
157  calls to do_step()
158 */
159  virtual void setup(const ParticleIndexes &) {};
160 
161  //! Perform a single time step
162  /** \param[in] sc the particles that should be moved
163  \param[in] dt maximum time step value
164  \return the amount that time should be advanced.
165  */
166  virtual double do_step(const ParticleIndexes &sc, double dt) = 0;
167 
168  //! Return true if the passed particle is appropriate for the simulation.
169  virtual bool get_is_simulation_particle(ParticleIndex p) const = 0;
170 
171  /** called by simulate() -
172  calls setup() and then calls do_step() iteratively
173  till given simulation time is completed
174 
175  @param time time to simulate
176 
177  @return score at end of simulation period
178  */
179  virtual double do_simulate(double time);
180 
181  /** Calls the protected method setup() and then calls
182  method do_step() iteratively, and using a self adjusting time
183  step that can grow up to max_time_step_factor times than
184  the default time step returned by get_maximum_time_step()
185 
186  \see simulate_wave()
187  */
188  virtual double do_simulate_wave(double time_in_fs, double max_time_step_factor = 10.0,
189  double base = 1.5);
190 
191  private:
192  double temperature_;
193  double max_time_step_;
194  double current_time_;
195  double last_time_step_;
196  double wave_factor_; // if >1.0, use simulate_wave() from do_optimize()
197 };
198 
200 
201 /**\name Energy conversions
202 
203  The native energy units in \imp are difficult to do any sort of math with.
204  One can convert the quantities into more useful ones.
205  @{
206 */
207 IMPATOMEXPORT double get_energy_in_femto_joules(double energy_in_kcal_per_mol);
208 IMPATOMEXPORT double get_force_in_femto_newtons(
209  double force_in_kcal_per_mol_per_angstrom);
210 
211 IMPATOMEXPORT double get_spring_constant_in_femto_newtons_per_angstrom(
212  double k_in_kcal_per_mol_per_angstrom_square);
213 
214 /** @} */
215 
216 IMPATOM_END_NAMESPACE
217 
218 #endif /* IMPATOM_SIMULATOR_H */
double get_kt(double T)
Return kT for a given temperature.
The base class for simulators.
Definition: Simulator.h:34
double get_current_time() const
Definition: Simulator.h:107
#define IMP_FINAL
Have the compiler report an error if anything overrides this method.
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:72
virtual void setup(const ParticleIndexes &)
Definition: Simulator.h:159
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:110
Base class for all optimizers.
Definition: Optimizer.h:46
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing sets of objects.
Definition: object_macros.h:42
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:20
Simple 3D vector class.
Class to handle individual model particles.
Definition: Particle.h:37
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.