IMP logo
IMP Reference Guide  2.17.0
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-2022 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(Floats, floats, Floats);
70  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Int, int, Int);
71  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Ints, ints, Ints);
72  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(String, string, String);
73  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Object, object, Object *);
74  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(WeakObject, weak_object, Object *);
75 
76  /** @name Float Attributes
77  Float attributes can be optimized, meaning an Optimizer class is
78  allowed to change their value in order to improve the score.
79  As a result, there are a number of specialized methods to manipulate
80  the value of float attributes.
81 
82  All distances are assumed to be in angstroms
83  and derivatives in kcal/mol/angstrom. This is not enforced.
84  */
85  /*@{*/
86  /** add attribute name to the attributes table of this particle
87 
88  @param name attribute key
89  @param initial_value initial value for the attribute
90  @param optimized whether to flag this attribute as optimized
91  */
92  void add_attribute(FloatKey name, const Float initial_value, bool optimized);
93 
94  /** Adds value to the derivatives table of the
95  specified particle attribute
96 
97  @param key the attribute key whose derivative is updated
98  @param value the derivative value to be added
99  @param da a derivative accumulator for reweighting derivatives
100  */
101  void add_to_derivative(FloatKey key, Float value,
102  const DerivativeAccumulator &da);
103 
104  void set_is_optimized(FloatKey k, bool tf);
105 
106  //! returns true if key k is marked by model as optimized
107  inline bool get_is_optimized(FloatKey k) const;
108 
109  //! returns the derivative of the specified particle attribute
110  inline Float get_derivative(FloatKey k) const;
111  /** @} */
112 
113  /** \name Particle attributes
114  @{
115  */
116  void add_attribute(ParticleIndexKey k, Particle *v);
117  bool has_attribute(ParticleIndexKey k);
118  void set_value(ParticleIndexKey k, Particle *v);
119  inline Particle *get_value(ParticleIndexKey k) const;
120  void remove_attribute(ParticleIndexKey k);
121  ParticleIndexKeys get_particle_keys() const;
122  /** @} */
123 
124  //! Print out all the attributes
125  void show(std::ostream &out = std::cout) const;
126 
127  //! Get whether the particle is active.
128  /** Restraints referencing the particle are only evaluated for 'active'
129  particles.
130  \return true it the particle is active.
131  */
132  bool get_is_active() const;
133 #endif
134 
135  //! returns the particle index of this particle in its model
136  ParticleIndex get_index() const;
137 
138 #if !defined(IMP_DOXYGEN)
139  void clear_caches() override;
140 #endif
141  protected:
142  virtual ModelObjectsTemp do_get_inputs() const override final {
143  return ModelObjectsTemp();
144  }
145  virtual ModelObjectsTemp do_get_outputs() const override final {
146  return ModelObjectsTemp();
147  }
148 };
149 
150 // for swig
151 class Decorator;
152 
153 /** Take Decorator or Particle. */
154 class IMPKERNELEXPORT ParticleAdaptor : public InputAdaptor {
155  Model *m_;
156  ParticleIndex pi_;
157 
158  public:
159  ParticleAdaptor() : m_(nullptr), pi_() {}
160  ParticleAdaptor(Particle *p) : m_(p->get_model()), pi_(p->get_index()) {}
161  ParticleAdaptor(const Decorator &d);
162 #ifndef SWIG
164  : m_(p->get_model()), pi_(p->get_index()) {}
166  : m_(p->get_model()), pi_(p->get_index()) {}
168  : m_(p->get_model()), pi_(p->get_index()) {}
169 #endif
170  Model *get_model() const { return m_; }
171  ParticleIndex get_particle_index() const { return pi_; }
172 };
173 
174 
175 /****************** Inline methods ***************/
176 
177 #ifndef IMP_DOXYGEN
178 
179 bool Particle::get_is_optimized(FloatKey k) const {
180  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
181  return get_model()->get_is_optimized(k, id_);
182 }
183 
184 Float Particle::get_derivative(FloatKey k) const {
185  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
186  return get_model()->get_derivative(k, id_);
187 }
188 
189 Particle *Particle::get_value(ParticleIndexKey k) const {
190  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
191  return get_model()->get_particle(get_model()->get_attribute(k, id_));
192 }
193 
194 #define IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(UCName, lcname, Value) \
195  void Particle::add_attribute(UCName##Key name, Value initial_value) { \
196  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
197  get_model()->add_attribute(name, id_, initial_value); \
198  } \
199  void Particle::remove_attribute(UCName##Key name) { \
200  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
201  get_model()->remove_attribute(name, id_); \
202  } \
203  bool Particle::has_attribute(UCName##Key name) const { \
204  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
205  return get_model()->get_has_attribute(name, id_); \
206  } \
207  Value Particle::get_value(UCName##Key name) const { \
208  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
209  return get_model()->get_attribute(name, id_); \
210  } \
211  void Particle::set_value(UCName##Key name, Value value) { \
212  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
213  get_model()->set_attribute(name, id_, value); \
214  } \
215  UCName##Keys Particle::get_##lcname##_keys() const { \
216  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
217  return get_model()->internal::UCName##AttributeTable::get_attribute_keys( \
218  id_); \
219  } \
220  void Particle::add_cache_attribute(UCName##Key name, Value value) { \
221  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
222  return get_model()->add_cache_attribute(name, id_, value); \
223  }
224 
225 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Float, float, Float);
226 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Floats, floats, Floats);
227 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Int, int, Int);
228 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Ints, ints, Ints);
229 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(String, string, String);
230 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Object, object, Object *);
231 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(WeakObject, weak_object, Object *);
232 
233 #endif // DOXYGEN
234 
235 IMPKERNEL_END_NAMESPACE
236 #endif /* IMPKERNEL_PARTICLE_H */
virtual ModelObjectsTemp do_get_outputs() const overridefinal
Definition: Particle.h:145
Basic types used by IMP.
Key< 0 > FloatKey
The type used to identify float attributes in the Particles.
Definition: base_types.h:32
Smart pointer to Object-derived classes that does not refcount.
Definition: WeakPointer.h:76
Functions and adaptors for dealing with particle indexes.
IMP::Vector< Float > Floats
Standard way to pass a bunch of Float values.
Definition: types.h:46
#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 smart pointer to a reference counted object.
Definition: Pointer.h:87
IMP::Vector< IMP::WeakPointer< ModelObject > > ModelObjectsTemp
Definition: base_types.h:89
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:26
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
Base class for objects in a Model that depend on other objects.
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.
virtual ModelObjectsTemp do_get_inputs() const overridefinal
Definition: Particle.h:142
A nullptr-initialized pointer to an IMP Object.
Helper macros for throwing and handling exceptions.
A shared base class to help in debugging and things.
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:19
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:34
ParticleIndex get_index() const
returns the particle index of this particle in its model
IMP::Vector< Int > Ints
Standard way to pass a bunch of Int values.
Definition: types.h:48
Convenience class to accept multiple input types.
Definition: InputAdaptor.h:25
Various general useful functions for IMP.
std::string String
Basic string value.
Definition: types.h:43
Class for adding derivatives from restraints to the model.