IMP logo
IMP Reference Guide  develop.f6c15b4169,2024/11/06
The Integrative Modeling Platform
estimates.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/estimates.h
3  * \brief Estimates of various physical quantities.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPATOM_ESTIMATES_H
9 #define IMPATOM_ESTIMATES_H
10 
11 #include <IMP/atom/atom_config.h>
12 #include "Residue.h"
13 #include <IMP/base_types.h>
14 
15 IMPATOM_BEGIN_NAMESPACE
16 /** @name Estimator Functions
17 
18  These functions allow you to estimate physical quantities
19  relating to biomolecules.
20 */
21 //!@{
22 
23 /*! Several protein density value references that have been proposed
24  * in the literature.
25  * - ALBER et al. (structure 2005) Estimated value 0.625 (1/1.60) Da/A3
26  * - HARPAZ et al. (1994) Computed value 0.826446=1/1.21 Da/A3
27  * - ANDERSSON and Hovmuller (1998) Computed value 1.22 g/cm3 ~ 0.7347 Da/A3
28  * - TSAI et al. (1999) Computed value 1.40 g/cm3 ~ 0.84309 Da/A3
29  * - QUILLIN and Matthews (2000) Computed value 1.43 g/cm3 ~ 0.86116 Da/A3
30  * - SQUIRE and Himmel (1979),
31  * Gekko and Noguchi (1979) Experimental value 1.37 g/cm3 ~ 0.82503 Da/A3
32  */
34  ALBER,
35  HARPAZ,
36  ANDERSSON,
37  TSAI,
38  QUILLIN,
39  SQUIRE
40 };
41 
42 //! returns the protein density value (in Da/A^3)
43 //! associated with a given reference
44 IMPATOMEXPORT double get_protein_density_from_reference
45 ( ProteinDensityReference densityReference );
46 
47 //! Estimate the volume of a protein from its mass
48 /**
49  * \param[in] m the mass for which we want to output the corresponding volume
50  * \param[in] ref the protein density reference used in the computation.
51  * As a default ref is the estimate published in Alber et. al, Structure 2005.
52 */
53 IMPATOMEXPORT double get_volume_from_mass
54 ( double m,
55  ProteinDensityReference ref = ALBER);
56 
57 //! Estimate the mass of a protein from its volume
58 /**
59  * \param[in] v the volume for which we want to output the corresponding mass
60  * \param[in] ref the protein density reference used in the computation.
61  * As a default ref is the estimate published in Alber et. al, Structure 2005.
62 */
63 IMPATOMEXPORT double get_mass_from_volume
64 ( double v,
65  ProteinDensityReference ref = ALBER );
66 
67 //! Estimate the mass of a protein from the number of amino acids
68 /** We use an estimate of 110 Daltons per residue, following Chimera.
69 
70  The mass is in Daltons.
71  */
72 IMPATOMEXPORT double get_mass_from_number_of_residues
73 ( unsigned int num_aa );
74 
75 //! Return an estimate for the volume of a given residue
76 /** The volume estimates are taken from
77  Pontius J, Richelle J, Wodak SJ.,
78  \external{https://www.ncbi.nlm.nih.gov/pubmed/8950272,
79  Deviations from standard atomic volumes as a quality measure for
80  protein crystal structures}, J Mol Biol. 1996 Nov 22;264(1):121-36.
81 
82 
83  \throw ValueException if a non-standard residue type is passed
84  */
85 IMPATOMEXPORT double get_volume_from_residue_type
86 ( ResidueType rt );
87 
88 //!@}
89 
90 /** Compute the concentration in molarity from the passed values*/
91 inline double get_molarity
92 ( double n,
93  double volume ) {
94  double v = volume;
95  // n*10^27/(v *6.02e23)
96  return n * 1e4 / (v * 6.02);
97 }
98 
99 /** Compute the concentration in molarity from the passed values*/
100 inline double get_kd
101 ( double na,
102  double nb,
103  double nab,
104  double volume ) {
105  return get_molarity(na, volume) * get_molarity(nb, volume) /
106  get_molarity(nab, volume);
107 }
108 
109 /** Return the predicted diffusion coefficient in Angstrom squared per
110  femtosecond at the specified radius and temperature.
111 
112  @param r radius in angstroms
113  @param temp temperature in Kelvin
114  (negative = default IMP temperature of 297.15K)
115 
116  See
117  \external{https://en.wikipedia.org/wiki/Einstein_relation_(kinetic_theory),
118  wikipedia} for a reference and
119  \external{https://en.wikipedia.org/wiki/Viscosity,Wikipedia on Viscosity}
120  for the values of the viscosity of water used.*/
121 IMPATOMEXPORT double get_einstein_diffusion_coefficient
122 ( double r,
123  double temp= -1);
124 
125 /** Return the predicted diffusion coefficient in radians squared per
126  femtosecond at the specified radius and temperature.
127 
128  @param r radius in angstroms
129  @param temp temperature in Kelvin
130  (negative = default IMP temperature of 297.15K)
131 
132 */
134 ( double r,
135  double temp= -1 );
136 
137 /** Return the standard deviation for the Brownian step in Angstroms given the
138  diffusion coefficient D in A^2/fs and the time step t in fs.*/
139 IMPATOMEXPORT double get_diffusion_length
140 ( double D, double t );
141 
142 /** Return the scale for diffusion in Angstroms given the specified force,
143  the diffusion coefficient D and the time step t.
144 
145  @param D diffusion coefficient in Angstrom^2/femtosecond
146  @param force applied force in kcal/mol/A
147  @param t time step in femtoseconds
148  @param temp temperature in Kelvin
149  (negative = default IMP temperature of 297.15K)
150 */
151 IMPATOMEXPORT double get_diffusion_length
152 ( double D,
153  double force,
154  double t,
155  double temp = -1);
156 
157 /** Get the standard deviation of the diffusion angle change in radians given
158  the rigid body diffusion coefficient in A^2/fs and the time step dtfs in fs.*/
159 IMPATOMEXPORT double get_diffusion_angle
160 ( double D,
161  double dtfs );
162 
163 /** Estimate the diffusion coefficient of a particle in A^2/fs from a list of
164  displacements each taken after the given time step dt. Removes any non-random
165  motion component (under the simplifying assumption it is constant over time)
166 
167  @param displacements displacement vectors in Angstroms
168  @param dt time step in femtoseconds
169 
170  @note The units of displacements and dt params could be actually
171  arbitrary. The units of the returned value will simply change to
172  e.g. cm^2/sec if displacements and dt are specified in cm and
173  seconds, resp.
174 
175 */
176 IMPATOMEXPORT double get_diffusion_coefficient
177 ( const algebra::Vector3Ds &displacements, double dt );
178 
179 /** Estimate the diffusion coefficient of a particle in A^2/fs from a list of
180  displacements each taken after the given time step dt. Removes any non-random
181  motion component (under the simplifying assumption it is constant over time)
182 
183  @param displacements displacement vectors in Angstroms
184  @param dts corresponding time steps in femtoseconds, expected to sum to more than zero
185 
186  @note The units of displacements and dt params could be actually
187  arbitrary. The units of thE returned value will simply change to
188  e.g. cm^2/sec if displacements and dts are specified in cm and
189  seconds, resp.
190 */
191 IMPATOMEXPORT double get_diffusion_coefficient
192 ( const algebra::Vector3Ds &displacements,
193  const Floats &dts);
194 
195 /** Estimate the rotational diffusion coefficient of a particle in Rad^2/fs
196  from a list of rotational orientations taken at consecutive time steps dt
197  (in fs). It is assumed that the mean angular rotation is zero (as it is otherwise
198  complicated to compute from a list of orientations - may require parameter
199  estimation of the folded-normal distribution)
200 */
201 IMPATOMEXPORT double get_rotational_diffusion_coefficient
202 ( const algebra::Rotation3Ds &orientations,
203  double dt );
204 
205 /**\name Energy conversions
206 
207  Convert energy from kcal/mol to femtojoules
208  @{
209 */
210 IMPATOMEXPORT double get_energy_in_femto_joules
211 ( double energy_in_kcal_per_mol );
212 
213 //! Convert force from kcal/mol/A to femtonewtons
214 IMPATOMEXPORT double get_force_in_femto_newtons
215 ( double force_in_kcal_per_mol_per_angstrom );
216 
217 //! Convert spring constant from kcal/mol/A^2 to femtonewton/A
219 ( double k_in_kcal_per_mol_per_angstrom_square );
220 
221 
222 
223 IMPATOM_END_NAMESPACE
224 
225 #endif /* IMPATOM_ESTIMATES_H */
double get_volume_from_residue_type(ResidueType rt)
Return an estimate for the volume of a given residue.
double get_einstein_rotational_diffusion_coefficient(double r, double temp=-1)
Basic types used by IMP.
double get_protein_density_from_reference(ProteinDensityReference densityReference)
double get_spring_constant_in_femto_newtons_per_angstrom(double k_in_kcal_per_mol_per_angstrom_square)
Convert spring constant from kcal/mol/A^2 to femtonewton/A.
double get_diffusion_length(double D, double force, double t, double temp=-1)
double get_mass_from_number_of_residues(unsigned int num_aa)
Estimate the mass of a protein from the number of amino acids.
double get_mass_from_volume(double v, ProteinDensityReference ref=ALBER)
Estimate the mass of a protein from its volume.
ProteinDensityReference
Definition: estimates.h:33
double get_kd(double na, double nb, double nab, double volume)
Definition: estimates.h:101
double get_diffusion_angle(double D, double dtfs)
double get_volume_from_mass(double m, ProteinDensityReference ref=ALBER)
Estimate the volume of a protein from its mass.
double get_rotational_diffusion_coefficient(const algebra::Rotation3Ds &orientations, double dt)
A decorator for Residues.
double get_molarity(double n, double volume)
Definition: estimates.h:92
double get_force_in_femto_newtons(double force_in_kcal_per_mol_per_angstrom)
Convert force from kcal/mol/A to femtonewtons.
double get_diffusion_coefficient(const algebra::Vector3Ds &displacements, const Floats &dts)
double get_einstein_diffusion_coefficient(double r, double temp=-1)