IMP  2.3.1
The Integrative Modeling Platform
FormFactorTable.h
Go to the documentation of this file.
1 /**
2  * \file IMP/saxs/FormFactorTable.h \brief A class for computation of
3  * atomic and residue level form factors for SAXS calculations
4  *
5  * Copyright 2007-2014 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPSAXS_FORM_FACTOR_TABLE_H
10 #define IMPSAXS_FORM_FACTOR_TABLE_H
11 
12 #include <IMP/saxs/saxs_config.h>
13 
14 #include <IMP/kernel/Particle.h>
15 #include <IMP/base_types.h>
16 #include <IMP/atom/Residue.h>
17 #include <IMP/atom/Atom.h>
18 #include <IMP/atom/element.h>
19 #include <IMP/algebra/utility.h>
20 
21 #include <iostream>
22 #include <vector>
23 
24 IMPSAXS_BEGIN_NAMESPACE
25 
26 //! type of the form factors for profile calculations
27 /*
28  ALL_ATOMS - all atoms including hydrogens
29  HEAVY_ATOMS - no hydrogens, all other atoms included
30  CA_ATOMS - residue level, residue represented by CA
31 */
33  ALL_ATOMS,
34  HEAVY_ATOMS,
35  CA_ATOMS
36 };
37 
38 /**
39  class that deals with form factor computation
40  two form factors are supported:
41  (i) zero form factors for faster approximated calculations
42  (ii) full form factors for slower accurate calculations
43 
44  Each form factor can be divided into two parts: vacuum and dummy.
45  dummy is an approximated excluded volume (solvent) form factor.
46  The approximation is done using Fraser, MacRae and Suzuki (1978) model.
47 */
48 class IMPSAXSEXPORT FormFactorTable {
49  public:
50  //! default constructor
52 
53  //! constructor with form factor table file (required for full form factors)
54  FormFactorTable(const String& table_name, Float min_q, Float max_q,
55  Float delta_q);
56 
57  // 1. Zero form factors
58 
59  //! get f(0), ie q=0 for real space profile calculation
60  Float get_form_factor(kernel::Particle* p,
61  FormFactorType ff_type = HEAVY_ATOMS) const;
62 
63  //! f(0) in vacuum
64  Float get_vacuum_form_factor(kernel::Particle* p,
65  FormFactorType ff_type = HEAVY_ATOMS) const;
66 
67  //! f(0) for solvent
68  Float get_dummy_form_factor(kernel::Particle* p,
69  FormFactorType ff_type = HEAVY_ATOMS) const;
70 
71  //! f(0) for water
72  Float get_water_form_factor() const { return zero_form_factors_[OH2]; }
73 
74  //! f(0) for water in vacuum
76  return vacuum_zero_form_factors_[OH2];
77  }
78 
79  //! f(0) for water (solvent)
81  return dummy_zero_form_factors_[OH2];
82  }
83 
84  // 2. Full form factors
85 
86  //! full form factor for reciprocal space profile calculation
87  const Floats& get_form_factors(kernel::Particle* p,
88  FormFactorType ff_type = HEAVY_ATOMS) const;
89 
90  //! for reciprocal space profile calculation
91  const Floats& get_vacuum_form_factors(kernel::Particle* p,
92  FormFactorType ff_type =
93  HEAVY_ATOMS) const;
94 
95  //! for reciprocal space profile calculation
96  const Floats& get_dummy_form_factors(kernel::Particle* p,
97  FormFactorType ff_type =
98  HEAVY_ATOMS) const;
99 
100  //! full water form factor
101  const Floats& get_water_form_factors() const { return form_factors_[OH2]; }
102 
103  //! full water vacuum form factor
105  return vacuum_form_factors_[OH2];
106  }
107 
108  //! full water dummy form factor
110  return dummy_form_factors_[OH2];
111  }
112 
113  //! radius
114  Float get_radius(kernel::Particle* p,
115  FormFactorType ff_type = HEAVY_ATOMS) const;
116 
117  //! volume
119  FormFactorType ff_type = HEAVY_ATOMS) const;
120 
121  //! print tables
122  void show(std::ostream& out = std::cout, std::string prefix = "") const;
123 
124  // electron density of solvent - default=0.334 e/A^3 (H2O)
125  static Float rho_;
126 
127  private:
128  // atom types for heavy atoms according to the number of hydrogens
129  // connected to them
130  // ALL_ATOM_SIZE is number of types needed for all atom representation
131  // this indexing is used in form_factors arrays
132  enum FormFactorAtomType {
133  H,
134  He,
135  Li,
136  Be,
137  B,
138  C,
139  N,
140  O,
141  F,
142  Ne, // periodic table, lines 1-2 (10)
143  Na,
144  Mg,
145  Al,
146  Si,
147  P,
148  S,
149  Cl,
150  Ar, // line 3 (8)
151  K,
152  Ca,
153  Cr,
154  Mn,
155  Fe,
156  Co,
157  Ni,
158  Cu,
159  Zn,
160  Se,
161  Br, // line 4 (11)
162  I,
163  Ir,
164  Pt,
165  Au,
166  Hg,
167  ALL_ATOM_SIZE = 34,
168  CH = 34,
169  CH2 = 35,
170  CH3 = 36,
171  NH = 37,
172  NH2 = 38,
173  NH3 = 39,
174  OH = 40,
175  OH2 = 41,
176  SH = 42,
177  HEAVY_ATOM_SIZE = 43,
178  UNK = 44
179  };
180 
181  // map between atom element and FormFactorAtomType
182  static std::map<atom::Element, FormFactorAtomType> element_ff_type_map_;
183 
184  struct FormFactor {
185  FormFactor() {}
186  FormFactor(double ff, double vacuum_ff, double dummy_ff)
187  : ff_(ff), vacuum_ff_(vacuum_ff), dummy_ff_(dummy_ff) {}
188  double ff_, vacuum_ff_, dummy_ff_;
189  };
190 
191  // map between residue type and residue level form factors
192  static std::map<atom::ResidueType, FormFactor> residue_type_form_factor_map_;
193 
194  // form factors for q=0, the order as in the FormFactorAtomType enum
195  static Float zero_form_factors_[];
196 
197  static Float vacuum_zero_form_factors_[];
198  // those represent excluded volume
199  static Float dummy_zero_form_factors_[];
200 
201  // a key for storing zero form factor in kernel::Particle as attribute
202  static IntKey form_factor_type_key_;
203 
204  // class for storing form factors solvation table
205  class AtomFactorCoefficients {
206  public:
207  String atom_type_;
208  Float a_[5];
209  Float b_[5];
210  Float c_;
211  Float excl_vol_;
212  };
213 
214  // read entry
215  friend std::istream& operator>>(
216  std::istream& s, AtomFactorCoefficients& atom_factor_coefficients);
217 
218  // write entry
219  friend std::ostream& operator<<(
220  std::ostream& s, const AtomFactorCoefficients& atom_factor_coefficients);
221 
222  private:
223  int read_form_factor_table(const String& table_name);
224 
225  void init_element_form_factor_map();
226 
227  void init_residue_type_form_factor_map();
228 
229  void compute_form_factors_all_atoms();
230 
231  void compute_form_factors_heavy_atoms();
232 
233  float get_form_factor(atom::ResidueType rt) const;
234 
235  float get_vacuum_form_factor(atom::ResidueType rt) const;
236 
237  float get_dummy_form_factor(atom::ResidueType rt) const;
238 
239  FormFactorAtomType get_form_factor_atom_type(atom::Element e) const;
240 
241  FormFactorAtomType get_form_factor_atom_type(kernel::Particle* p,
242  FormFactorType ff_type) const;
243 
244  FormFactorAtomType get_carbon_atom_type(const atom::AtomType& atom_type,
245  const atom::ResidueType& residue_type)
246  const;
247 
248  FormFactorAtomType get_nitrogen_atom_type(
249  const atom::AtomType& atom_type,
250  const atom::ResidueType& residue_type) const;
251 
252  FormFactorAtomType get_oxygen_atom_type(const atom::AtomType& atom_type,
253  const atom::ResidueType& residue_type)
254  const;
255 
256  FormFactorAtomType get_sulfur_atom_type(const atom::AtomType& atom_type,
257  const atom::ResidueType& residue_type)
258  const;
259 
260  private:
261  // read from lib file
262  std::vector<AtomFactorCoefficients> form_factors_coefficients_;
263 
264  // table of full form factors for 14 atom types
265  std::vector<Floats> form_factors_;
266 
267  // vacuum full form factors for 14 atom types
268  std::vector<Floats> vacuum_form_factors_;
269 
270  // dummy full form factors for 14 atom types
271  std::vector<Floats> dummy_form_factors_;
272 
273  // min/max q and sampling resolution for form factor computation
274  Float min_q_, max_q_, delta_q_;
275 
276  base::WarningContext warn_context_;
277 };
278 
279 /** Get the default table.*/
280 IMPSAXSEXPORT FormFactorTable* get_default_form_factor_table();
281 
282 IMPSAXS_END_NAMESPACE
283 
284 #endif /* IMPSAXS_FORM_FACTOR_TABLE_H */
Define the elements used in IMP.
Import IMP/kernel/base_types.h in the namespace.
Key< 1, true > IntKey
The type used to identify int attributes in the Particles.
Simple atom decorator.
Float get_water_form_factor() const
f(0) for water
FormFactorTable * get_default_form_factor_table()
const Floats & get_water_form_factors() const
full water form factor
double get_volume(const BoundingBoxD< D > &bb)
Definition: BoundingBoxD.h:147
Functions to deal with very common math operations.
A decorator for Residues.
const ResidueType UNK
Unknown residue.
Float get_vacuum_water_form_factor() const
f(0) for water in vacuum
const Floats & get_water_dummy_form_factors() const
full water dummy form factor
Class to handle individual model particles.
Classes to handle individual model particles. (Note that implementation of inline functions in in int...
void show(Hierarchy h, std::ostream &out=std::cout)
Print out a molecular hierarchy.
IMP::kernel::Particle Particle
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:20
const Floats & get_water_vacuum_form_factors() const
full water vacuum form factor
FormFactorType
type of the form factors for profile calculations
Float get_dummy_water_form_factor() const
f(0) for water (solvent)
Element
The various elements currently supported/known.
Definition: element.h:23
std::string String
Basic string value.
Definition: types.h:44