IMP logo
IMP Reference Guide  2.11.1
The Integrative Modeling Platform
Particle.h
Go to the documentation of this file.
1 /**
2  * \file IMP/Particle.h
3  * \brief Classes to handle individual model particles.
4  * (Note that implementation of inline functions is in internal)
5  *
6  * Copyright 2007-2019 IMP Inventors. All rights reserved.
7  *
8  */
9 
10 #ifndef IMPKERNEL_PARTICLE_H
11 #define IMPKERNEL_PARTICLE_H
12 
13 #include <IMP/kernel_config.h>
14 #include "base_types.h"
15 #include "DerivativeAccumulator.h"
16 #include "Model.h"
17 #include "ModelObject.h"
18 #include "particle_index.h"
19 #include "Key.h"
20 #include "internal/AttributeTable.h"
21 #include <IMP/Object.h>
22 #include <IMP/base_utility.h>
23 #include <IMP/Pointer.h>
24 #include <IMP/check_macros.h>
25 #include <utility>
26 
27 IMPKERNEL_BEGIN_NAMESPACE
28 
29 //class Model;
30 class Changed;
31 class SaveOptimizeds;
32 
33 //! Class to handle individual particles of a Model object.
34 /** A particle is a lightweight object that serves as a place holder for the
35  particle index in a given Model object. The Model object itself stores
36  the particle attributes of various types:
37  Float, Int, String, Object, and WeakObject, and any data concerning the
38  optimization of these particles by Optimizer and Simulator classes.
39 
40 */
41 class IMPKERNELEXPORT Particle : public ModelObject {
42  private:
43 // doxygen produces funny docs for these things
44 #ifndef IMP_DOXYGEN
45  friend class Model;
46 #endif
47  ParticleIndex id_;
49 
50  public:
51  //! Construct a particle and add it to the Model
52  Particle(Model *m, std::string name);
53 
54  //! Construct a particle and add it to the Model
55  Particle(Model *m);
56 
57 #ifndef IMP_DOXYGEN
58 
59 #define IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(UCName, lcname, Value) \
60  inline void add_attribute(UCName##Key name, Value initial_value); \
61  inline void remove_attribute(UCName##Key name); \
62  inline bool has_attribute(UCName##Key name) const; \
63  inline Value get_value(UCName##Key name) const; \
64  inline void set_value(UCName##Key name, Value value); \
65  inline void add_cache_attribute(UCName##Key name, Value value); \
66  inline UCName##Keys get_##lcname##_keys() const
67 
68  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Float, float, Float);
69  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Int, int, Int);
70  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(String, string, String);
71  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Object, object, Object *);
72  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(WeakObject, weak_object, Object *);
73 
74  /** @name Float Attributes
75  Float attributes can be optimized, meaning an Optimizer class is
76  allowed to change their value in order to improve the score.
77  As a result, there are a number of specialized methods to manipulate
78  the value of float attributes.
79 
80  All distances are assumed to be in angstroms
81  and derivatives in kcal/mol/angstrom. This is not enforced.
82  */
83  /*@{*/
84  /** add attribute name to the attributes table of this particle
85 
86  @param name attribute key
87  @param initial_value initial value for the attribute
88  @param optimized whether to flag this attribute as optimized
89  */
90  void add_attribute(FloatKey name, const Float initial_value, bool optimized);
91 
92  /** Adds value to the derivatives table of the
93  specified particle attribute
94 
95  @param key the attribute key whose derivative is updated
96  @param value the derivative value to be added
97  @param da a derivative accumulator for reweighting derivatives
98  */
99  void add_to_derivative(FloatKey key, Float value,
100  const DerivativeAccumulator &da);
101 
102  void set_is_optimized(FloatKey k, bool tf);
103 
104  //! returns true if key k is marked by model as optimized
105  inline bool get_is_optimized(FloatKey k) const;
106 
107  //! returns the derivative of the specified particle attribute
108  inline Float get_derivative(FloatKey k) const;
109  /** @} */
110 
111  /** \name Particle attributes
112  @{
113  */
114  void add_attribute(ParticleIndexKey k, Particle *v);
115  bool has_attribute(ParticleIndexKey k);
116  void set_value(ParticleIndexKey k, Particle *v);
117  inline Particle *get_value(ParticleIndexKey k) const;
118  void remove_attribute(ParticleIndexKey k);
119  ParticleIndexKeys get_particle_keys() const;
120  /** @} */
121 
122  //! Print out all the attributes
123  void show(std::ostream &out = std::cout) const;
124 
125  //! Get whether the particle is active.
126  /** Restraints referencing the particle are only evaluated for 'active'
127  particles.
128  \return true it the particle is active.
129  */
130  bool get_is_active() const;
131 #endif
132 
133  //! returns the particle index of this particle in its model
134  ParticleIndex get_index() const;
135 
136 #if !defined(IMP_DOXYGEN)
137  void clear_caches();
138 #endif
139  protected:
141  return ModelObjectsTemp();
142  }
144  return ModelObjectsTemp();
145  }
146 };
147 
148 // for swig
149 class Decorator;
150 
151 /** Take Decorator or Particle. */
152 class IMPKERNELEXPORT ParticleAdaptor : public InputAdaptor {
153  Model *m_;
154  ParticleIndex pi_;
155 
156  public:
157  ParticleAdaptor() : m_(nullptr), pi_() {}
158  ParticleAdaptor(Particle *p) : m_(p->get_model()), pi_(p->get_index()) {}
159  ParticleAdaptor(const Decorator &d);
160 #ifndef SWIG
162  : m_(p->get_model()), pi_(p->get_index()) {}
164  : m_(p->get_model()), pi_(p->get_index()) {}
166  : m_(p->get_model()), pi_(p->get_index()) {}
167 #endif
168  Model *get_model() const { return m_; }
169  ParticleIndex get_particle_index() const { return pi_; }
170 };
171 
172 
173 /****************** Inline methods ***************/
174 
175 #ifndef IMP_DOXYGEN
176 
177 bool Particle::get_is_optimized(FloatKey k) const {
178  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
179  return get_model()->get_is_optimized(k, id_);
180 }
181 
182 Float Particle::get_derivative(FloatKey k) const {
183  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
184  return get_model()->get_derivative(k, id_);
185 }
186 
187 Particle *Particle::get_value(ParticleIndexKey k) const {
188  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
189  return get_model()->get_particle(get_model()->get_attribute(k, id_));
190 }
191 
192 #define IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(UCName, lcname, Value) \
193  void Particle::add_attribute(UCName##Key name, Value initial_value) { \
194  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
195  get_model()->add_attribute(name, id_, initial_value); \
196  } \
197  void Particle::remove_attribute(UCName##Key name) { \
198  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
199  get_model()->remove_attribute(name, id_); \
200  } \
201  bool Particle::has_attribute(UCName##Key name) const { \
202  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
203  return get_model()->get_has_attribute(name, id_); \
204  } \
205  Value Particle::get_value(UCName##Key name) const { \
206  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
207  return get_model()->get_attribute(name, id_); \
208  } \
209  void Particle::set_value(UCName##Key name, Value value) { \
210  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
211  get_model()->set_attribute(name, id_, value); \
212  } \
213  UCName##Keys Particle::get_##lcname##_keys() const { \
214  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
215  return get_model()->internal::UCName##AttributeTable::get_attribute_keys( \
216  id_); \
217  } \
218  void Particle::add_cache_attribute(UCName##Key name, Value value) { \
219  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
220  return get_model()->add_cache_attribute(name, id_, value); \
221  }
222 
223 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Float, float, Float);
224 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Int, int, Int);
225 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(String, string, String);
226 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Object, object, Object *);
227 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(WeakObject, weak_object, Object *);
228 
229 #endif // DOXYGEN
230 
231 IMPKERNEL_END_NAMESPACE
232 #endif /* IMPKERNEL_PARTICLE_H */
virtual ModelObjectsTemp do_get_outputs() const
Definition: Particle.h:143
Basic types used by IMP.
Key< 0 > FloatKey
The type used to identify float attributes in the Particles.
Definition: base_types.h:32
virtual ModelObjectsTemp do_get_inputs() const
Definition: Particle.h:140
Smart pointer to Object-derived classes that does not refcount.
Definition: WeakPointer.h:76
Various general useful functions for IMP.
#define IMP_FINAL
Have the compiler report an error if anything overrides this method.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Class for adding derivatives from restraints to the model.
Storage of a model, its restraints, constraints and particles.
Keys to cache lookup of attribute strings.
virtual void clear_caches()
Definition: Object.h:227
A more IMP-like version of the std::vector.
Definition: Vector.h:39
A smart pointer to a reference counted object.
Definition: Pointer.h:87
IMP::Vector< IMP::WeakPointer< ModelObject > > ModelObjectsTemp
Definition: base_types.h:82
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
Key< 3 > ParticleIndexKey
The type used to identify a particle attribute in the Particles.
Definition: base_types.h:44
Ints get_index(const ParticlesTemp &particles, const Subset &subset, const Subsets &excluded)
Common base class for heavy weight IMP objects.
Definition: Object.h:106
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:146
Single variable function.
Interface to specialized Particle types (e.g. atoms)
Definition: Decorator.h:118
std::ostream & show(Hierarchy h, std::ostream &out=std::cout)
Print the hierarchy using a given decorator to display each node.
A nullptr-initialized pointer to an IMP Object.
Exception definitions and assertions.
A shared base class to help in debugging and things.
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:20
Class to handle individual particles of a Model object.
Definition: Particle.h:41
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
int Int
Basic integer value.
Definition: types.h:35
ParticleIndex get_index() const
returns the particle index of this particle in its model
Various general useful functions for IMP.
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.