IMP  2.2.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-2014 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/kernel/Particle.h>
15 #include <IMP/Optimizer.h>
16 #include <IMP/kernel/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 give number of frames.
33  */
34 class IMPATOMEXPORT Simulator : public Optimizer {
35  public:
36  /**
37  @param m model associated with simulater
38  @param name simulater 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(kernel::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 a given time, by calling the protected
54  method do_step() iteratively.
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 a given time, by calling the protected
64  method do_step() iteratively, and using a self adjusting time
65  step that can grow up to max_time_step_factor times than
66  the default time step returned by get_maximum_time_step()
67 
68  @param time_in_fs time_in_fs in femtoseconds
69  @param max_time_step_factor the maximal factor by which the
70  maximum time step is exceeded
71  @param base base by which time step increases or decreases
72  during the wave
73 
74  @note This function is experimental and liable to change at any
75  time.
76  */
77  double simulate_wave(double time_in_fs, double max_time_step_factor = 10.0,
78  double base = 1.5);
79 
80  double get_temperature() const { return temperature_; }
81  void set_temperature(double d) { temperature_ = d; }
82  /** \name Time steps
83  The simulator has a maximum allowed time step. It can take
84  shorter ones if needed due to stability concerns.
85 
86  As with all times in \imp, the time step is in fs.
87  @{
88  */
89  void set_maximum_time_step(double ts) { max_time_step_ = ts; }
90  double get_maximum_time_step() const { return max_time_step_; }
91  double get_last_time_step() const {
92  if (last_time_step_ < 0)
93  return get_maximum_time_step();
94  else
95  return last_time_step_;
96  }
97 /** @} */
98 #ifndef IMP_DOXYGEN
99  void set_time_step(double ts) { set_maximum_time_step(ts); }
100 #endif
101 
102  double get_kt() const;
103 
104  /**
105  returns the simulation time in femtoseconds that was performed
106  by this simulator since it was constructed
107  @note this time can be tweaked using set_current_time() )
108  */
109  double get_current_time() const { return current_time_; }
110 
111  /**
112  Sets the current simulation time in femtoseconds to ct.
113  */
114  void set_current_time(double ct) { current_time_ = ct; }
115 
116  /** Returns the set of particles used in the simulation. If a non-empty
117  set of particles was provided explicitly by earlier calls to the
118  particles list accessor methods, eg, add_particles(), this set
119  it returned. Otherwise, the associated kernel::Model object is
120  searched for appropriate particles that have a mass and XYZ
121  decorators.
122 
123  \see add_particle()
124  \see add_particles()
125  \see remove_particle()
126  \see clear_particles()
127  \see set_particles()
128  \see set_particles_order()
129  */
130  kernel::ParticlesTemp get_simulation_particles() const;
131 
132  /**
133  Same as get_simulation_particles(), but returns particle
134  model indexes.
135 
136  \see get_simulation_particles()
137  */
138  kernel::ParticleIndexes get_simulation_particle_indexes() const;
139 
140  /** \name Explicitly accessing the particles list
141 
142  One can explicitly specify which particles should be used for
143  the simulation, or retrieve information about the list of particles.
144  Each particle must be a Mass and core::XYZ particle. If none are
145  specified, the model is searched for appropriate particles, based
146  on the get_simulation_particles() method, which can be overridden
147  by child classes.
148  @{
149  */
150  IMP_LIST(public, Particle, particle, kernel::Particle *, kernel::Particles);
151 
152  protected:
153  /** @} */
154  virtual Float do_optimize(unsigned int max_steps) IMP_OVERRIDE IMP_FINAL;
155 
156  /** A Simulator class can perform setup operations before a series
157  of simulation steps is taken. */
158  virtual void setup(const kernel::ParticleIndexes &) {};
159 
160  /** Perform a single time step and return the amount that time
161  should be advanced. A maximum time step value is passed.
162  */
163  virtual double do_step(const kernel::ParticleIndexes &sc, double dt) = 0;
164 
165  /** Return true if the passed particle is appropriate for
166  the simulation.
167  */
168  virtual bool get_is_simulation_particle(kernel::ParticleIndex p) const = 0;
169 
170  private:
171  // see simulate() documentation
172  double do_simulate(double time);
173  // see simulate_wave() documentation
174  double do_simulate_wave(double time_in_fs, double max_time_step_factor = 10.0,
175  double base = 1.5);
176  double temperature_;
177  double max_time_step_;
178  double current_time_;
179  double last_time_step_;
180  double wave_factor_; // if >1.0, use simulate_wave() from do_optimize()
181 };
182 
184 
185 /**\name Energy conversions
186 
187  The native energy units in \imp are difficult to do any sort of math with.
188  One can convert the quantities into more useful ones.
189  @{
190 */
191 IMPATOMEXPORT double get_energy_in_femto_joules(double energy_in_kcal_per_mol);
192 IMPATOMEXPORT double get_force_in_femto_newtons(
193  double force_in_kcal_per_mol_per_angstrom);
194 
195 IMPATOMEXPORT double get_spring_constant_in_femto_newtons_per_angstrom(
196  double k_in_kcal_per_mol_per_angstrom_square);
197 
198 /** @} */
199 
200 IMPATOM_END_NAMESPACE
201 
202 #endif /* IMPATOM_SIMULATOR_H */
double get_kt(double T)
The base class for simulators.
Definition: Simulator.h:34
double get_current_time() const
Definition: Simulator.h:109
Import IMP/kernel/Optimizer.h in the namespace.
void set_current_time(double ct)
Definition: Simulator.h:114
Class to handle individual model particles.
Base class for all optimizers.
Classes to handle individual model particles.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing sets of objects.
virtual void setup(const kernel::ParticleIndexes &)
Definition: Simulator.h:158
double Float
Basic floating-point value (could be float, double...)
Definition: base/types.h:20
Simple 3D vector class.
#define IMP_LIST(protection, Ucname, lcname, Data, PluralData)
A macro to provide a uniform interface for storing lists of objects.
virtual double do_optimize(unsigned int ns)=0
override this function to do actual optimization
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:72