IMP  2.2.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* default_form_factor_table();
281 
282 IMPSAXS_END_NAMESPACE
283 
284 #endif /* IMPSAXS_FORM_FACTOR_TABLE_H */
FormFactorTable * default_form_factor_table()
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
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
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.
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: base/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: base/types.h:44