IMP logo
IMP Reference Guide  develop.5d113ecbfd,2023/06/06
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-2023 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 #include <cereal/access.hpp>
27 #include <cereal/types/base_class.hpp>
28 
29 IMPKERNEL_BEGIN_NAMESPACE
30 
31 //class Model;
32 class Changed;
33 class SaveOptimizeds;
34 
35 //! Class to handle individual particles of a Model object.
36 /** A particle is a lightweight object that serves as a place holder for the
37  particle index in a given Model object. The Model object itself stores
38  the particle attributes of various types:
39  Float, Int, String, Object, and WeakObject, and any data concerning the
40  optimization of these particles by Optimizer and Simulator classes.
41 
42 */
43 class IMPKERNELEXPORT Particle : public ModelObject {
44  private:
45 // doxygen produces funny docs for these things
46 #ifndef IMP_DOXYGEN
47  friend class Model;
48 #endif
49  ParticleIndex id_;
51 
52  public:
53  //! Construct a particle and add it to the Model
54  Particle(Model *m, std::string name);
55 
56  //! Construct a particle and add it to the Model
57  Particle(Model *m);
58 
59 #ifndef IMP_DOXYGEN
60  Particle() {}
61 
62 #define IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(UCName, lcname, Value) \
63  inline void add_attribute(UCName##Key name, Value initial_value); \
64  inline void remove_attribute(UCName##Key name); \
65  inline bool has_attribute(UCName##Key name) const; \
66  inline Value get_value(UCName##Key name) const; \
67  inline void set_value(UCName##Key name, Value value); \
68  inline void add_cache_attribute(UCName##Key name, Value value); \
69  inline UCName##Keys get_##lcname##_keys() const
70 
71  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Float, float, Float);
72  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Floats, floats, Floats);
73  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Int, int, Int);
74  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Ints, ints, Ints);
75  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(String, string, String);
76  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(Object, object, Object *);
77  IMP_KERNEL_PARTICLE_ATTRIBUTE_TYPE_DECL(WeakObject, weak_object, Object *);
78 
79  /** @name Float Attributes
80  Float attributes can be optimized, meaning an Optimizer class is
81  allowed to change their value in order to improve the score.
82  As a result, there are a number of specialized methods to manipulate
83  the value of float attributes.
84 
85  All distances are assumed to be in angstroms
86  and derivatives in kcal/mol/angstrom. This is not enforced.
87  */
88  /*@{*/
89  /** add attribute name to the attributes table of this particle
90 
91  @param name attribute key
92  @param initial_value initial value for the attribute
93  @param optimized whether to flag this attribute as optimized
94  */
95  void add_attribute(FloatKey name, const Float initial_value, bool optimized);
96 
97  /** Adds value to the derivatives table of the
98  specified particle attribute
99 
100  @param key the attribute key whose derivative is updated
101  @param value the derivative value to be added
102  @param da a derivative accumulator for reweighting derivatives
103  */
104  void add_to_derivative(FloatKey key, Float value,
105  const DerivativeAccumulator &da);
106 
107  void set_is_optimized(FloatKey k, bool tf);
108 
109  //! returns true if key k is marked by model as optimized
110  inline bool get_is_optimized(FloatKey k) const;
111 
112  //! returns the derivative of the specified particle attribute
113  inline Float get_derivative(FloatKey k) const;
114  /** @} */
115 
116  /** \name Particle attributes
117  @{
118  */
119  void add_attribute(ParticleIndexKey k, Particle *v);
120  bool has_attribute(ParticleIndexKey k);
121  void set_value(ParticleIndexKey k, Particle *v);
122  inline Particle *get_value(ParticleIndexKey k) const;
123  void remove_attribute(ParticleIndexKey k);
124  ParticleIndexKeys get_particle_keys() const;
125  /** @} */
126 
127  //! Print out all the attributes
128  void show(std::ostream &out = std::cout) const;
129 
130  //! Get whether the particle is active.
131  /** Restraints referencing the particle are only evaluated for 'active'
132  particles.
133  \return true it the particle is active.
134  */
135  bool get_is_active() const;
136 #endif
137 
138  //! returns the particle index of this particle in its model
139  ParticleIndex get_index() const;
140 
141 #if !defined(IMP_DOXYGEN)
142  void clear_caches() override;
143 #endif
144  protected:
145  virtual ModelObjectsTemp do_get_inputs() const override final {
146  return ModelObjectsTemp();
147  }
148  virtual ModelObjectsTemp do_get_outputs() const override final {
149  return ModelObjectsTemp();
150  }
151 
152  private:
153  friend class cereal::access;
154  template<class Archive> void serialize(Archive &ar) {
155  ar(cereal::base_class<ModelObject>(this), id_);
156  }
157 };
158 
159 // for swig
160 class Decorator;
161 
162 /** An adaptor that enable to implicitly pass particles to other
163  functions or constructors by passing either the particle itself
164  (in Python), a decorator to the particle, or a raw/smart IMP
165  pointer to the particle (in C++)
166 */
167 class IMPKERNELEXPORT ParticleAdaptor : public InputAdaptor {
168  Model *m_;
169  ParticleIndex pi_;
170 
171  public:
172  ParticleAdaptor() : m_(nullptr), pi_() {}
173  //! convert p to itself
174  ParticleAdaptor(Particle *p) : m_(p->get_model()), pi_(p->get_index()) {}
175  //! convert d to the particle it decorates
176  ParticleAdaptor(const Decorator &d);
177 #ifndef SWIG
179  : m_(p->get_model()), pi_(p->get_index()) {}
180  ParticleAdaptor(IMP::WeakPointer<Particle> p)
181  : m_(p->get_model()), pi_(p->get_index()) {}
182  ParticleAdaptor(IMP::PointerMember<Particle> p)
183  : m_(p->get_model()), pi_(p->get_index()) {}
184 #endif
185  Model *get_model() const { return m_; }
186  ParticleIndex get_particle_index() const { return pi_; }
187 };
188 
189 
190 /****************** Inline methods ***************/
191 
192 #ifndef IMP_DOXYGEN
193 
194 bool Particle::get_is_optimized(FloatKey k) const {
195  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
196  return get_model()->get_is_optimized(k, id_);
197 }
198 
199 Float Particle::get_derivative(FloatKey k) const {
200  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
201  return get_model()->get_derivative(k, id_);
202 }
203 
204 Particle *Particle::get_value(ParticleIndexKey k) const {
205  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used.");
206  return get_model()->get_particle(get_model()->get_attribute(k, id_));
207 }
208 
209 #define IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(UCName, lcname, Value) \
210  void Particle::add_attribute(UCName##Key name, Value initial_value) { \
211  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
212  get_model()->add_attribute(name, id_, initial_value); \
213  } \
214  void Particle::remove_attribute(UCName##Key name) { \
215  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
216  get_model()->remove_attribute(name, id_); \
217  } \
218  bool Particle::has_attribute(UCName##Key name) const { \
219  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
220  return get_model()->get_has_attribute(name, id_); \
221  } \
222  Value Particle::get_value(UCName##Key name) const { \
223  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
224  return get_model()->get_attribute(name, id_); \
225  } \
226  void Particle::set_value(UCName##Key name, Value value) { \
227  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
228  get_model()->set_attribute(name, id_, value); \
229  } \
230  UCName##Keys Particle::get_##lcname##_keys() const { \
231  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
232  return get_model()->internal::UCName##AttributeTable::get_attribute_keys( \
233  id_); \
234  } \
235  void Particle::add_cache_attribute(UCName##Key name, Value value) { \
236  IMP_USAGE_CHECK(get_is_active(), "Inactive particle used."); \
237  return get_model()->add_cache_attribute(name, id_, value); \
238  }
239 
240 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Float, float, Float);
241 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Floats, floats, Floats);
242 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Int, int, Int);
243 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Ints, ints, Ints);
244 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(String, string, String);
245 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(Object, object, Object *);
246 IMP_PARTICLE_ATTRIBUTE_TYPE_DEF(WeakObject, weak_object, Object *);
247 
248 #endif // DOXYGEN
249 
250 IMPKERNEL_END_NAMESPACE
251 #endif /* IMPKERNEL_PARTICLE_H */
virtual ModelObjectsTemp do_get_outputs() const overridefinal
Definition: Particle.h:148
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:77
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.
Index< ParticleIndexTag > ParticleIndex
Definition: base_types.h:161
Keys to cache lookup of attribute strings.
virtual void clear_caches()
Definition: Object.h:270
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:86
Base class for objects in a Model that depend on other objects.
Definition: ModelObject.h:28
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:111
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:143
Base class for objects in a Model that depend on other objects.
Interface to specialized Particle types (e.g. atoms)
Definition: Decorator.h:119
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:145
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:43
#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
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.
ParticleAdaptor(Particle *p)
convert p to itself
Definition: Particle.h:174