IMP logo
IMP Reference Guide  develop.cb6747d2d1,2024/03/28
The Integrative Modeling Platform
Diffusion.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Diffusion.h
3  * \brief A decorator for a diffusing particle.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPATOM_DIFFUSION_H
10 #define IMPATOM_DIFFUSION_H
11 
12 #include <IMP/atom/atom_config.h>
13 
14 #include <IMP/core/XYZR.h>
15 #include <IMP/algebra/Vector3D.h>
16 #include <IMP/internal/constants.h>
17 
18 #include <vector>
19 #include <limits>
20 
21 IMPATOM_BEGIN_NAMESPACE
22 
23 //! A decorator for a diffusing particle with a diffusion coefficient.
24 /** Diffusion is used to decorate a particle with XYZ coordinates (since it
25  inhertis from XYZ) and a translational diffusion coefficient D.
26  D is specified in units of \f$A^2/fs\f$, and it is used by eg
27  IMP's Brownian dynamics simulator. It can be set explicitly or inferred
28  implicitly from the radius.
29 
30  \ingroup helper
31  \ingroup decorators
32  \include Diffusion_decorator.py
33  \see RigidBodyDiffusion
34  \see BrownianDynamics
35  */
36 class IMPATOMEXPORT Diffusion : public IMP::core::XYZ {
37  static void do_setup_particle(Model *m, ParticleIndex pi,
38  Float D) {
39  if(!XYZ::get_is_setup(m,pi))
40  {
42  }
43  m->add_attribute(get_diffusion_coefficient_key(), pi, D);
44  }
45  static void do_setup_particle(Model *m, ParticleIndex pi,
46  const algebra::Vector3D &v, Float D) {
47  if(XYZ::get_is_setup(m,pi))
48  {
49  XYZ(m,pi).set_coordinates(v);
50  }
51  else
52  {
53  XYZ::setup_particle(m, pi, v);
54  }
55  do_setup_particle(m, pi, D);
56  }
57 
58  /**
59  Same as do_setup_particle(m, pi, D) but D is automatically set
60  to IMP::atom::get_einstein_diffusion_coefficient(radius) for radius
61  IMP::core::XYZR(m, pi).get_radius().
62 
63  Note a different D should probably be set manually if the temperature is
64  not the default IMP temperature (297.15).
65  */
66  static void do_setup_particle(Model *m, ParticleIndex pi);
67 
68  public:
70  //! Setup the particle with the specified diffusion coefficient
71  /**
72  If the particle does not have coordinates, it is decorated as XYZ
73  and its coordinates are set to [0,0,0], otherwise the coordinates
74  remain the same.
75  */
77  //! Setup the particle with the specified coordinates and diffusion coefficient
79  //! Setup the particle with a diffusion coefficient automatically
80  //! inferred from its radius using the Stokes-Einstein equation.
81  /**
82  The diffusion coefficient is computed implicitly using the
83  Stokes-Einstein equation by calling
84  IMP::atom::get_einstein_diffusion_coefficient(R), where the
85  Stokes radius R is core::XYZR::get_radius() and the temperature
86  is the default IMP temperature of 297.15K.
87 
88  \note If the simulation temperature or particle radius change,
89  the diffusion coefficient must be changed explicitly e.g., using
90  set_diffusion_coefficient()
91  \note This constructor can be used only on particles that have
92  a radius field, e.g. decorated as IMP::core::XYZR.
93  */
95 
96  //! Return true if the particle is an instance of Diffusion
97  static bool get_is_setup(Model *m, ParticleIndex p) {
98  return m->get_has_attribute(get_diffusion_coefficient_key(), p) &&
99  XYZ::get_is_setup(m, p);
100  }
101  //! set diffusion coefficient in \f$A^2/fs\f$
102  void set_diffusion_coefficient(double d) {
103  get_particle()->set_value(get_diffusion_coefficient_key(), d);
104 
105  }
106  //! get diffusion coefficient in \f$A^2/fs\f$
107  double get_diffusion_coefficient() const {
108  return get_model()->get_attribute(get_diffusion_coefficient_key(),
110  }
111  //! Get the D key
112  static FloatKey get_diffusion_coefficient_key();
113 };
114 
115 IMPATOMEXPORT double get_diffusion_coefficient_from_cm2_per_second(double din);
116 
117 IMP_DECORATORS(Diffusion, Diffusions, core::XYZs);
118 
119 /** A rigid body that is diffusing, so it also has coordinates and a
120  rotational diffusion coefficient. The units on the rotational
121  coefficient are \f$radians^2/fs\f$.
122 
123  The translational and rotational diffusion coefficients are computed
124  automatically using
125  IMP::atom::get_einstein_diffusion_coefficient(radius) and
126  IMP::atom::get_einstein_rotational_diffusion_coefficient(radius)
127  for radius IMP::core::XYZR(m, pi).get_radius() and default IMP
128  temperature of 297.15, but they can be overridden explicitly.
129 
130  Note that different translational and rotational coefficients should probably
131  be set manually if the temperature is not the default IMP temperature.
132 
133  \see Diffusion
134  \see BrownianDynamics
135 */
136 class IMPATOMEXPORT RigidBodyDiffusion : public Diffusion {
137  static void do_setup_particle(Model *m, ParticleIndex pi);
138 
139  public:
141  //! Setup this particle with automatically inferred translation and
142  //! rotational diffusion coefficients
143  /**
144  The diffusion coefficients are computed using
145  core::XYZR::get_radius() for the Stokes radius and the
146  default IMP temperature of 297.15K.
147 
148  \note If the simulation temperature or particle radius change,
149  the diffusion coefficient must be changed explicitly e.g., using
150  set_diffusion_coefficient()
151  \note The particle must have been decorated with core::XYZR
152  for this constructor to be used
153  The diffusion coefficients are inferred automatically from the particle's radius
154  using IMP::atom::get_einstein_diffusion_coefficient(radius) and
155  IMP::atom::get_einstein_rotational_diffusion_coefficient(radius).
156  */
158 
159  //! returns the rotational diffusion coefficient in \f$radians^2/fs\f$
161  return get_model()->get_attribute
162  (get_rotational_diffusion_coefficient_key(),
164  }
165 
166 
167  //! sets the rotational diffusion coefficient in \f$radians^2/fs\f$
169  return get_particle()->set_value(get_rotational_diffusion_coefficient_key(),
170  d);
171  }
172 
173  //! Return true if the particle is an instance of an RigidBodyDiffusion
174  static bool get_is_setup(Model *m, ParticleIndex p) {
175  return m->get_has_attribute(get_rotational_diffusion_coefficient_key(), p) &&
176  Diffusion::get_is_setup(m, p);
177  }
178 
179  //! Get the D key
180  static FloatKey get_rotational_diffusion_coefficient_key();
181 };
182 
183 IMP_DECORATORS(RigidBodyDiffusion, RigidBodyDiffusions, Diffusions);
184 
185 IMPATOM_END_NAMESPACE
186 
187 #endif /* IMPATOM_DIFFUSION_H */
ParticleIndex get_particle_index() const
Returns the particle index decorated by this decorator.
Definition: Decorator.h:211
static bool get_is_setup(Model *m, ParticleIndex p)
Return true if the particle is an instance of an RigidBodyDiffusion.
Definition: Diffusion.h:174
#define IMP_DECORATOR_SETUP_1(Name, FirstArgumentType, first_argument_name)
Model * get_model() const
Returns the Model containing the particle.
Definition: Decorator.h:214
static XYZ setup_particle(Model *m, ParticleIndex pi)
Definition: XYZ.h:51
double get_diffusion_coefficient() const
get diffusion coefficient in
Definition: Diffusion.h:107
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
void set_rotational_diffusion_coefficient(double d) const
sets the rotational diffusion coefficient in
Definition: Diffusion.h:168
void set_diffusion_coefficient(double d)
set diffusion coefficient in
Definition: Diffusion.h:102
void add_attribute(TypeKey attribute_key, ParticleIndex particle, Type value)
add particle attribute with the specified key and initial value
#define IMP_DECORATOR_SETUP_2(Name, FirstArgumentType, first_argument_name,SecondArgumentType, second_argument_name)
A decorator for a particle with x,y,z coordinates.
Definition: XYZ.h:30
#define IMP_DECORATOR_SETUP_0(Name)
static bool get_is_setup(Model *m, ParticleIndex p)
Return true if the particle is an instance of Diffusion.
Definition: Diffusion.h:97
Particle * get_particle() const
Returns the particle decorated by this decorator.
Definition: Decorator.h:194
#define IMP_DECORATOR_METHODS(Name, Parent)
VectorD< 3 > Vector3D
Definition: VectorD.h:408
double get_rotational_diffusion_coefficient() const
returns the rotational diffusion coefficient in
Definition: Diffusion.h:160
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:19
Simple 3D vector class.
#define IMP_DECORATORS(Name, PluralName, Parent)
Define the types for storing sets of decorators.
bool get_has_attribute(TypeKey attribute_key, ParticleIndex particle) const
return true if particle has attribute with the specified key
A decorator for a diffusing particle with a diffusion coefficient.
Definition: Diffusion.h:36
Type get_attribute(TypeKey attribute_key, ParticleIndex particle)
get the value of the particle attribute with the specified key
Decorator for a sphere-like particle.