IMP logo
IMP Reference Guide  2.20.2
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-2022 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/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 
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  RESIDUES - residue level, represented by residue bead
32 */
34  ALL_ATOMS,
35  HEAVY_ATOMS,
36  CA_ATOMS,
37  RESIDUES
38 };
39 
40 /**
41  class that deals with form factor computation
42  two form factors are supported:
43  (i) zero form factors for faster approximated calculations
44  (ii) full form factors for slower accurate calculations
45 
46  Each form factor can be divided into two parts: vacuum and dummy.
47  dummy is an approximated excluded volume (solvent) form factor.
48  The approximation is done using Fraser, MacRae and Suzuki (1978) model.
49 */
50 class IMPSAXSEXPORT FormFactorTable {
51  public:
52  //! default constructor
54 
55  //! constructor with form factor table file (required for full form factors)
56  FormFactorTable(const std::string& table_name, double min_q, double max_q,
57  double delta_q);
58 
59  // 1. Zero form factors
60 
61  //! get f(0), ie q=0 for real space profile calculation
62  double get_form_factor(Particle* p,
63  FormFactorType ff_type = HEAVY_ATOMS) const;
64 
65  //! f(0) in vacuum
66  double get_vacuum_form_factor(Particle* p,
67  FormFactorType ff_type = HEAVY_ATOMS) const;
68 
69  //! f(0) for solvent
70  double get_dummy_form_factor(Particle* p,
71  FormFactorType ff_type = HEAVY_ATOMS) const;
72 
73  //! f(0) for water
74  double get_water_form_factor() const { return zero_form_factors_[OH2]; }
75 
76  //! f(0) for water in vacuum
78  return vacuum_zero_form_factors_[OH2];
79  }
80 
81  //! f(0) for water (solvent)
82  double get_dummy_water_form_factor() const {
83  return dummy_zero_form_factors_[OH2];
84  }
85 
86  // 2. Full form factors
87 
88  //! full form factor for reciprocal space profile calculation
89  const Vector<double>& get_form_factors(Particle* p,
90  FormFactorType ff_type = HEAVY_ATOMS) const;
91 
92  //! for reciprocal space profile calculation
93  const Vector<double>& get_vacuum_form_factors(Particle* p,
94  FormFactorType ff_type = HEAVY_ATOMS) const;
95 
96  //! for reciprocal space profile calculation
97  const Vector<double>& get_dummy_form_factors(Particle* p,
98  FormFactorType ff_type = HEAVY_ATOMS) const;
99 
100  //! full water form factor
102  return form_factors_[OH2];
103  }
104 
105  //! full water vacuum form factor
107  return vacuum_form_factors_[OH2];
108  }
109 
110  //! full water dummy form factor
112  return dummy_form_factors_[OH2];
113  }
114 
115  //! radius
116  double get_radius(Particle* p, FormFactorType ff_type = HEAVY_ATOMS) const;
117 
118  //! volume
119  double get_volume(Particle* p, 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 double 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  Ag,
163  I,
164  Ir,
165  Pt,
166  Au,
167  Hg,
168  ALL_ATOM_SIZE = 35,
169  CH = 35,
170  CH2 = 36,
171  CH3 = 37,
172  NH = 38,
173  NH2 = 39,
174  NH3 = 40,
175  OH = 41,
176  OH2 = 42,
177  SH = 43,
178  HEAVY_ATOM_SIZE = 44,
179  UNK = 45
180  };
181 
182  // map between atom element and FormFactorAtomType
183  static std::map<atom::Element, FormFactorAtomType> element_ff_type_map_;
184 
185  struct FormFactor {
186  FormFactor() {}
187  FormFactor(double ff, double vacuum_ff, double dummy_ff)
188  : ff_(ff), vacuum_ff_(vacuum_ff), dummy_ff_(dummy_ff) {}
189  double ff_, vacuum_ff_, dummy_ff_;
190  };
191 
192  // map between residue type and residue level form factors
193  static std::map<atom::ResidueType, FormFactor> residue_type_form_factor_map_;
194 
195  // form factors for q=0, the order as in the FormFactorAtomType enum
196  static double zero_form_factors_[];
197 
198  static double vacuum_zero_form_factors_[];
199  // those represent excluded volume
200  static double dummy_zero_form_factors_[];
201 
202  // a key for storing zero form factor in Particle as attribute
203  static IntKey form_factor_type_key_;
204 
205  // class for storing form factors solvation table
206  class AtomFactorCoefficients {
207  public:
208  std::string atom_type_;
209  double a_[5];
210  double b_[5];
211  double c_;
212  double excl_vol_;
213  };
214 
215 #ifndef SWIG
216  // read entry
217  friend std::istream& operator>>(
218  std::istream& s, AtomFactorCoefficients& atom_factor_coefficients);
219 
220  // write entry
221  friend std::ostream& operator<<(
222  std::ostream& s, const AtomFactorCoefficients& atom_factor_coefficients);
223 #endif
224 
225  private:
226  int read_form_factor_table(const std::string& table_name);
227 
228  void init_element_form_factor_map();
229 
230  void init_residue_type_form_factor_map();
231 
232  void compute_form_factors_all_atoms();
233 
234  void compute_form_factors_heavy_atoms();
235 
236  double get_form_factor(atom::ResidueType rt) const;
237 
238  double get_vacuum_form_factor(atom::ResidueType rt) const;
239 
240  double get_dummy_form_factor(atom::ResidueType rt) const;
241 
242  FormFactorAtomType get_form_factor_atom_type(atom::Element e) const;
243 
244  FormFactorAtomType get_form_factor_atom_type(Particle* p,
245  FormFactorType ff_type) const;
246 
247  FormFactorAtomType get_carbon_atom_type(const atom::AtomType& atom_type,
248  const atom::ResidueType& residue_type)
249  const;
250 
251  FormFactorAtomType get_nitrogen_atom_type(
252  const atom::AtomType& atom_type,
253  const atom::ResidueType& residue_type) const;
254 
255  FormFactorAtomType get_oxygen_atom_type(const atom::AtomType& atom_type,
256  const atom::ResidueType& residue_type)
257  const;
258 
259  FormFactorAtomType get_sulfur_atom_type(const atom::AtomType& atom_type,
260  const atom::ResidueType& residue_type)
261  const;
262 
263  private:
264  // read from lib file
265  Vector<AtomFactorCoefficients> form_factors_coefficients_;
266 
267  // table of full form factors for 14 atom types
268  Vector<Vector<double> > form_factors_;
269 
270  // vacuum full form factors for 14 atom types
271  Vector<Vector<double> > vacuum_form_factors_;
272 
273  // dummy full form factors for 14 atom types
274  Vector<Vector<double> > dummy_form_factors_;
275 
276  // min/max q and sampling resolution for form factor computation
277  double min_q_, max_q_, delta_q_;
278 
279  WarningContext warn_context_;
280 };
281 
282 /** Get the default table.*/
283 IMPSAXSEXPORT FormFactorTable* get_default_form_factor_table();
284 
285 IMPSAXS_END_NAMESPACE
286 
287 #endif /* IMPSAXS_FORM_FACTOR_TABLE_H */
Define the elements used in IMP.
Basic types used by IMP.
const Vector< double > & get_water_dummy_form_factors() const
full water dummy form factor
Simple atom decorator.
double get_water_form_factor() const
f(0) for water
FormFactorTable * get_default_form_factor_table()
double get_volume(const BoundingBoxD< D > &bb)
See BoundingBoxD.
Definition: BoundingBoxD.h:170
Functions to deal with very common math operations.
A decorator for Residues.
const ResidueType UNK
Unknown residue.
Key< 1 > IntKey
The type used to identify int attributes in the Particles.
Definition: base_types.h:36
const Vector< double > & get_water_vacuum_form_factors() const
full water vacuum form factor
double get_dummy_water_form_factor() const
f(0) for water (solvent)
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
std::ostream & show(Hierarchy h, std::ostream &out=std::cout)
Print the hierarchy using a given decorator to display each node.
const Vector< double > & get_water_form_factors() const
full water form factor
Class to handle individual particles of a Model object.
Definition: Particle.h:43
FormFactorType
type of the form factors for profile calculations
Element
The various elements currently supported/known.
Definition: element.h:23
double get_vacuum_water_form_factor() const
f(0) for water in vacuum