IMP logo
IMP Reference Guide  2.6.2
The Integrative Modeling Platform
Model.h
Go to the documentation of this file.
1 /**
2  * \file IMP/Model.h
3  * \brief Storage of a model, its restraints, constraints and particles.
4  *
5  * Copyright 2007-2016 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPKERNEL_MODEL_H
10 #define IMPKERNEL_MODEL_H
11 
12 #include <IMP/kernel_config.h>
13 #include "ModelObject.h"
14 #include "ScoringFunction.h"
15 #include "Restraint.h"
16 #include "RestraintSet.h"
17 #include "ScoreState.h"
18 #include "container_macros.h"
19 #include "base_types.h"
20 //#include "Particle.h"
21 #include "Undecorator.h"
22 #include "internal/AttributeTable.h"
23 #include "internal/attribute_tables.h"
24 #include <IMP/Object.h>
25 #include <IMP/Pointer.h>
26 #include <boost/unordered_map.hpp>
27 #include <boost/unordered_set.hpp>
28 #include <IMP/tuple_macros.h>
29 #include <boost/iterator/transform_iterator.hpp>
30 #include <boost/iterator/filter_iterator.hpp>
31 
32 #include <limits>
33 
34 IMPKERNEL_BEGIN_NAMESPACE
35 
36 class ModelObject;
37 class Undecorator;
38 class Particle;
39 
40 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
41 namespace internal {
42 enum Stage {
43  NOT_EVALUATING,
44  BEFORE_EVALUATING,
45  EVALUATING,
46  AFTER_EVALUATING,
47  COMPUTING_DEPENDENCIES
48 };
49 }
50 #endif
51 
52 class Model;
53 
54 //! Class for storing model, its restraints, constraints, and particles.
55 /** The Model maintains a standard \imp container for each of Particle,
56  ScoreState and Restraint object types.
57 
58  Each Float attribute has an associated range which reflects the
59  range of values that it is expected to take on during optimization.
60  The optimizer can use these ranges to make the optimization process
61  more efficient. By default, the range estimates are simply the
62  range of values for that attribute in the various particles, but
63  it can be set to another value. For example, an attribute storing
64  an angle could have the range set to (0,PI).
65 
66  The ranges are not enforced; they are just guidelines. In order to
67  enforce ranges, see, for example,
68  IMP::example::ExampleSingletonModifier.
69 
70  \headerfile Model.h "IMP/Model.h"
71  */
72 class IMPKERNELEXPORT Model : public Object
73 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
74  ,
75  public internal::Masks,
76  // The attribute tables provide fast access to
77  // e.g. particle attributes, etc.
78  public internal::FloatAttributeTable,
79  public internal::StringAttributeTable,
80  public internal::IntAttributeTable,
81  public internal::ObjectAttributeTable,
82  public internal::WeakObjectAttributeTable,
83  public internal::IntsAttributeTable,
84  public internal::ObjectsAttributeTable,
85  public internal::ParticleAttributeTable,
86  public internal::ParticlesAttributeTable
87 #endif
88  {
90  // must be up top
91  // we don't want any liveness checks
92  IMP_NAMED_TUPLE_5(NodeInfo, NodeInfos, Edges, inputs, Edges, input_outputs,
93  Edges, outputs, Edges, readers, Edges, writers, );
94  typedef boost::unordered_map<const ModelObject *, NodeInfo> DependencyGraph;
95  DependencyGraph dependency_graph_;
96  boost::unordered_set<const ModelObject *> no_dependencies_;
97  boost::unordered_map<const ModelObject *, ScoreStatesTemp>
98  required_score_states_;
99 
100  // basic representation
101  boost::unordered_map<FloatKey, FloatRange> ranges_;
102 
103  ParticleIndexes free_particles_;
106 
107  Vector<PointerMember<Object> > model_data_;
108 
109  void do_add_dependencies(const ModelObject *mo);
110  void do_clear_required_score_states(ModelObject *mo);
111  void do_check_required_score_states(const ModelObject *mo) const;
112  void do_check_update_order(const ScoreState *ss) const;
113  void do_check_inputs_and_outputs(const ModelObject *mo) const;
114  void do_check_readers_and_writers(const ModelObject *mo) const;
115  void do_check_not_in_readers_and_writers(const ModelObject *mo) const;
116  void do_clear_dependencies(const ModelObject *mo);
117 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
118  // things the evaluate template functions need, can't be bothered with friends
119  public:
120 #endif
121  // check more things on the first call
122  bool first_call_;
123  // the stage of evaluation
124  internal::Stage cur_stage_;
125 
126  ModelObjectsTemp get_dependency_graph_inputs(const ModelObject *mo) const;
127  ModelObjectsTemp get_dependency_graph_outputs(const ModelObject *mo) const;
128  bool do_get_has_dependencies(const ModelObject *mo) const {
129  return no_dependencies_.find(mo) == no_dependencies_.end();
130  }
131  void do_set_has_dependencies(const ModelObject *mo, bool tf);
132  void do_set_has_all_dependencies(bool tf);
133 
134  void validate_computed_derivatives() const {}
135  void set_has_all_dependencies(bool tf);
136  bool get_has_all_dependencies() const;
137  void check_dependency_invariants() const;
138  void check_dependency_invariants(const ModelObject *mo) const;
139  ScoreStatesTemp get_ancestor_score_states(const ModelObject *mo) const;
140  ScoreStatesTemp get_descendent_score_states(const ModelObject *mo) const;
141 
142  void before_evaluate(const ScoreStatesTemp &states);
143  void after_evaluate(const ScoreStatesTemp &states, bool calc_derivs);
144 
145  internal::Stage get_stage() const { return cur_stage_; }
146  ParticleIndex add_particle_internal(Particle *p);
147  static void do_remove_score_state(ScoreState *obj);
148  void do_add_score_state(ScoreState *obj);
149  void do_remove_particle(ParticleIndex pi);
150  bool do_get_has_required_score_states(const ModelObject *mo) const;
151  void do_set_has_required_score_states(ModelObject *mo, bool tf);
152  const ScoreStatesTemp &do_get_required_score_states(const ModelObject *mo)
153  const {
154  IMP_USAGE_CHECK(do_get_has_required_score_states(mo),
155  "Doesn't have score states");
156  return required_score_states_.find(mo)->second;
157  }
158  void do_add_model_object(ModelObject *mo);
159  void do_remove_model_object(ModelObject *mo);
160 
161  public:
162  //! Construct an empty model
163  Model(std::string name = "Model %1%");
164 
165  public:
166 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
167  IMP_MODEL_IMPORT(internal::FloatAttributeTable);
168  IMP_MODEL_IMPORT(internal::StringAttributeTable);
169  IMP_MODEL_IMPORT(internal::IntAttributeTable);
170  IMP_MODEL_IMPORT(internal::ObjectAttributeTable);
171  IMP_MODEL_IMPORT(internal::WeakObjectAttributeTable);
172  IMP_MODEL_IMPORT(internal::IntsAttributeTable);
173  IMP_MODEL_IMPORT(internal::ObjectsAttributeTable);
174  IMP_MODEL_IMPORT(internal::ParticleAttributeTable);
175  IMP_MODEL_IMPORT(internal::ParticlesAttributeTable);
176 #endif
177  //! Clear all the cache attributes of a given particle.
178  void clear_particle_caches(ParticleIndex pi);
179 
180  //! Add particle to the model
181  ParticleIndex add_particle(std::string name);
182 
183  //! Get the name of a particle
184  std::string get_particle_name(ParticleIndex pi);
185 
186  //! Add the passed Undecorator to the particle.
187  void add_undecorator(ParticleIndex pi, Undecorator *d);
188 
189  /** @name States
190 
191  ScoreStates can be added to the Model in order to keep them
192  alive as long as the model is alive. Being added does affect
193  their ability to perform their required action. See ScoreState
194  for more information.
195 
196  \advancedmethod
197  */
198  /**@{*/
199  IMP_LIST_ACTION(public, ScoreState, ScoreStates, score_state, score_states,
200  ScoreState *, ScoreStates, do_add_score_state(obj), {},
201  do_remove_score_state(obj));
202  /**@}*/
203 
204  public:
205 #ifndef SWIG
206  using Object::clear_caches;
207 #endif
208 
209  //! Sometimes it is useful to be able to make sure the model is up to date
210  /** This method updates all the state but does not necessarily compute the
211  score. Use this to make sure that your containers and rigid bodies are
212  up to date.
213  */
214  void update();
215 
216 #ifdef IMP_DOXYGEN
217  /** \name Accessing attributes
218  \anchor model_attributes
219  All the attribute data associated with each Particle is stored in the
220  Model. For each type of attribute, there are the methods detailed below
221  (where, eg, TypeKey is FloatKey or StringKey)
222  @{
223  */
224  /** \pre get_has_attribute(attribute_key, particle) is false*/
225  void add_attribute(TypeKey attribute_key, ParticleIndex particle, Type value);
226 
227  /** \pre get_has_attribute(attribute_key, particle) is true*/
228  void remove_attribute(TypeKey attribute_key, ParticleIndex particle);
229 
230  bool get_has_attribute(TypeKey attribute_key, ParticleIndex particle) const;
231 
232  /** \pre get_has_attribute(attribute_key, particle) is true*/
233  void set_attribute(TypeKey attribute_key, ParticleIndex particle, Type value);
234 
235  /** \pre get_has_attribute(attribute_key, particle) is true*/
236  Type get_attribute(TypeKey attribute_key, ParticleIndex particle);
237 
238  /** Cache attributes, unlike normal attributes, can be added during
239  evaluation. They are also cleared by the clear_cache_attributes() method.
240  Cache attributes should be used when one is adding data to a particle
241  to aid scoring (eg cache the rigid body collision acceleration structure).
242 
243  When some pertinent aspect of the particle changes, the clear method
244  should
245  be called (yes, this is a bit vague). Examples where it should be cleared
246  include changing the set of members of a core::RigidBody or their
247  coordinates, changing the members of an atom::Hierarchy.
248  */
249  void add_cache_attribute(TypeKey attribute_key, ParticleIndex particle,
250  Type value);
251 
252  //! Optimized attributes are the parameters of the model
253  /** They will be modified by the samplers and optimizers.
254  */
255  void set_is_optimized(TypeKey attribute_key, ParticleIndex particle,
256  bool true_or_false);
257 /** @} */
258 #endif
259 
260 #ifdef SWIG
261 #define IMP_MODEL_ATTRIBUTE_METHODS(Type, Value) \
262  void add_attribute(Type##Key attribute_key, ParticleIndex particle, \
263  Value value); \
264  void remove_attribute(Type##Key attribute_key, ParticleIndex particle); \
265  bool get_has_attribute(Type##Key attribute_key, \
266  ParticleIndex particle) const; \
267  void set_attribute(Type##Key attribute_key, ParticleIndex particle, \
268  Value value); \
269  Value get_attribute(Type##Key attribute_key, ParticleIndex particle); \
270  void add_cache_attribute(Type##Key attribute_key, ParticleIndex particle, \
271  Value value)
272 
273  IMP_MODEL_ATTRIBUTE_METHODS(Float, Float);
274  IMP_MODEL_ATTRIBUTE_METHODS(Int, Int);
275  IMP_MODEL_ATTRIBUTE_METHODS(Ints, Ints);
276  IMP_MODEL_ATTRIBUTE_METHODS(String, String);
277  IMP_MODEL_ATTRIBUTE_METHODS(ParticleIndexes, ParticleIndexes);
278  IMP_MODEL_ATTRIBUTE_METHODS(ParticleIndex, ParticleIndex);
279  IMP_MODEL_ATTRIBUTE_METHODS(Object, Object *);
280  IMP_MODEL_ATTRIBUTE_METHODS(WeakObject, Object *);
281  void set_is_optimized(FloatKey, ParticleIndex, bool);
282  void add_to_derivative(FloatKey k, ParticleIndex particle, double v,
283  const DerivativeAccumulator &da);
284 #endif
285 
286  //! Get the particle from an index.
287  Particle *get_particle(ParticleIndex p) const;
288 
289  //! Check whether a given particle index exists.
290  bool get_has_particle(ParticleIndex p) const;
291 
292  //! Get all particle indexes
293  ParticleIndexes get_particle_indexes();
294 
295  //! Get all the ModelObjects associated with this Model.
296  ModelObjectsTemp get_model_objects() const;
297 
298  //! Remove a particle from the Model.
299  /** The particle will then be inactive and cannot be used for anything
300  and all data stored in the particle is lost.
301  */
302  void remove_particle(ParticleIndex pi);
303 
304  /** \name Storing data in the model
305 
306  One can store data associated with the model. This is used, for example,
307  to keep a central ScoreState to normalize rigid body rotational variables.
308  @{ */
309  //! Store a piece of data in the model referenced by the key.
310  void add_data(ModelKey mk, Object *o);
311  //! Get back some data stored in the model.
312  Object *get_data(ModelKey mk) const;
313  //! Remove data stored in the model.
314  void remove_data(ModelKey mk);
315  //! Check if the model has a certain piece of data attached.
316  bool get_has_data(ModelKey mk) const;
317  /** @} */
318 
320 
321  public:
322 #if !defined(IMP_DOXYGEN)
323  virtual void do_destroy() IMP_OVERRIDE;
324 #endif
325 };
326 
327 IMPKERNEL_END_NAMESPACE
328 
329 // This is needed for per cpp compilations, a not even sure why
330 // (perhaps cause Model returns ParticleIterator here and there?)
331 // - Feel free to remove if you *really* know what you're doing
332 #include "IMP/Particle.h"
333 
334 #endif /* IMPKERNEL_MODEL_H */
Basic types used by IMP.
Used to hold a set of related restraints.
boost::graph DependencyGraph
A directed graph on the interactions between the various objects in the model.
The base class for decorators.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
void add_particle(RMF::FileHandle fh, Particle *hs)
Various general useful macros for IMP.
virtual void clear_caches()
Definition: Object.h:227
Macros to define containers of objects.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
virtual void do_destroy()
Definition: Object.h:231
Common base class for heavy weight IMP objects.
Definition: Object.h:106
ScoreStates maintain invariants in the Model.
Definition: ScoreState.h:53
Shared score state.
Single variable function.
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
A nullptr-initialized pointer to an IMP Object.
A shared base class to help in debugging and things.
Represents a scoring function on the model.
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:20
Class to handle individual model particles.
Definition: Particle.h:37
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
Abstract base class for all restraints.
int Int
Basic integer value.
Definition: types.h:35
std::string String
Basic string value.
Definition: types.h:44
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
Class for adding derivatives from restraints to the model.