IMP  2.0.1
The Integrative Modeling Platform
atom/Atom.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Atom.h \brief Simple atom decorator.
3  *
4  * Copyright 2007-2013 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPATOM_ATOM_H
9 #define IMPATOM_ATOM_H
10 
11 #include <IMP/atom/atom_config.h>
12 #include "atom_macros.h"
13 #include "Residue.h"
14 #include "Hierarchy.h"
15 #include "element.h"
16 #include <IMP/core/utility.h>
17 #include <IMP/core/XYZ.h>
18 
19 #include <IMP/base_types.h>
20 #include <IMP/Particle.h>
21 #include <IMP/Model.h>
22 
23 #include <vector>
24 #include <deque>
25 
26 IMPATOM_BEGIN_NAMESPACE
27 
28 IMP_DECLARE_CONTROLLED_KEY_TYPE(AtomType, IMP_ATOM_TYPE_INDEX);
29 /** \class IMP::atom::AtomType
30  \brief The type of an atom.
31 
32  The standard Atom names in %IMP are derived from the PDB names as follows:
33  - the AtomType of a protein, DNA or RNA atom is the AtomType
34  created from the PDB atom name string with spaces removed. For
35  example, a protein C-alpha has the name AtomType("CA").
36  - the AtomType for a hetero (HETATM) atom is the AtomType created by
37  prefixing "HET:" to the PBD atom name string (this time without
38  spaces removed). For example, a calcium atom is AtomType("HET:CA ").
39 
40  We provide an AtomType instance for each of the standard PDB %atom types.
41  These have names such as IMP::atom::AT_N. The full list is elided for
42  readability.
43 
44  An AtomType implies an element (and hence a mass). While we have the
45  associations set up for protein, DNA and RNA atoms, it may be necessary
46  to add them for hetero atoms. You can use the add_atom_type() function
47  to do this.
48 
49  All atoms have the mass stored internally using a Mass decorator.
50 
51  \see IMP::atom::Atom
52 */
53 
54 /* each static must be on a separate line because of MSVC bug C2487:
55  see http://support.microsoft.com/kb/127900/
56 */
57 /** \relatesalso AtomType */
58 IMPATOMEXPORT extern const AtomType AT_UNKNOWN;
59 /** \relatesalso AtomType */
60 IMPATOMEXPORT extern const AtomType AT_N;
61 /** \relatesalso AtomType */
62 IMPATOMEXPORT extern const AtomType AT_CA;
63 #ifndef IMP_DOXYGEN
64 /** \relatesalso AtomType */
65 IMPATOMEXPORT extern const AtomType AT_C;
66 /** \relatesalso AtomType */
67 IMPATOMEXPORT extern const AtomType AT_O;
68 /** \relatesalso AtomType */
69 IMPATOMEXPORT extern const AtomType AT_H;
70 /** \relatesalso AtomType */
71 IMPATOMEXPORT extern const AtomType AT_H1;
72 /** \relatesalso AtomType */
73 IMPATOMEXPORT extern const AtomType AT_H2;
74 /** \relatesalso AtomType */
75 IMPATOMEXPORT extern const AtomType AT_H3;
76 /** \relatesalso AtomType */
77 IMPATOMEXPORT extern const AtomType AT_HA;
78 /** \relatesalso AtomType */
79 IMPATOMEXPORT extern const AtomType AT_HA1;
80 /** \relatesalso AtomType */
81 IMPATOMEXPORT extern const AtomType AT_HA2;
82 /** \relatesalso AtomType */
83 IMPATOMEXPORT extern const AtomType AT_HA3;
84 /** \relatesalso AtomType */
85 IMPATOMEXPORT extern const AtomType AT_CB;
86 /** \relatesalso AtomType */
87 IMPATOMEXPORT extern const AtomType AT_HB;
88 /** \relatesalso AtomType */
89 IMPATOMEXPORT extern const AtomType AT_HB1;
90 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HB2;
91 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HB3;
92 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OXT;
93 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CH3;
94 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CH;
95 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG;
96 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG1;
97 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG2;
98 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG;
99 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG1;
100 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG2;
101 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG3;
102 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG11;
103 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG21;
104 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG31;
105 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG12;
106 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG13;
107 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG22;
108 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG23;
109 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG32;
110 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OG;
111 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OG1;
112 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_SG;
113 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD;
114 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD1;
115 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD2;
116 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD;
117 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD1;
118 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD2;
119 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD3;
120 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD11;
121 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD21;
122 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD31;
123 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD12;
124 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD13;
125 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD22;
126 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD23;
127 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD32;
128 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_SD;
129 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OD1;
130 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OD2;
131 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_ND1;
132 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_ND2;
133 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE;
134 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE1;
135 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE2;
136 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE3;
137 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE;
138 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE1;
139 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE2;
140 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE3;
141 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE21;
142 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE22;
143 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OE1;
144 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OE2;
145 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE;
146 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE1;
147 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE2;
148 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ;
149 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ2;
150 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ3;
151 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NZ;
152 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ;
153 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ1;
154 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ2;
155 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ3;
156 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CH2;
157 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NH1;
158 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NH2;
159 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OH;
160 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH;
161 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH11;
162 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH21;
163 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH2;
164 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH12;
165 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH22;
166 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH13;
167 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH23;
168 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH33;
169 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_P;
170 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OP1;
171 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OP2;
172 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OP3;
173 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O5p;
174 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C5p;
175 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5p;
176 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5pp;
177 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C4p;
178 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H4p;
179 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O4p;
180 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C1p;
181 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H1p;
182 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C3p;
183 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H3p;
184 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O3p;
185 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C2p;
186 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H2p;
187 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H2pp;
188 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2p;
189 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HO2p;
190 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N9;
191 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C8;
192 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H8;
193 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N7;
194 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C5;
195 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C4;
196 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N3;
197 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C2;
198 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N1;
199 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C6;
200 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N6;
201 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H61;
202 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H62;
203 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O6;
204 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N2;
205 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NT;
206 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H21;
207 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H22;
208 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H6;
209 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5;
210 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2;
211 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N4;
212 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H41;
213 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H42;
214 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O4;
215 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C7;
216 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H71;
217 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H72;
218 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H73;
219 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O1A;
220 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2A;
221 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O3A;
222 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O1B;
223 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2B;
224 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O3B;
225 #endif
226 
227 
228 //! A decorator for a particle representing an atom.
229 /** Atoms always are Mass particles.
230  \ingroup hierarchy
231  \see Hierarchy
232  */
233 class IMPATOMEXPORT Atom:
234  public Hierarchy
235 {
236 public:
237 
238  IMP_DECORATOR(Atom, Hierarchy);
239 
240  Particle* get_particle() const {
241  return Hierarchy::get_particle();
242  }
243 
244  /** Create a decorator with the passed type.*/
245  static Atom setup_particle(Model *m,
246  ParticleIndex pi,
247  AtomType t);
248 
249  /** Create a decorator with the passed type.*/
250  static Atom setup_particle(Particle *p, AtomType t) {
251  return setup_particle(p->get_model(),
252  p->get_index(), t);
253  }
254 
255  /** Create a decorator by copying from o.*/
256  static Atom setup_particle(Particle *p, Atom o);
257 
258  //! return true if the particle has the needed attributes
259  static bool particle_is_instance(Particle *p) {
260  return p->has_attribute(get_atom_type_key())
261  && Hierarchy::particle_is_instance(p);
262  }
263 
264  AtomType get_atom_type() const {
265  return AtomType(get_particle()->get_value(get_atom_type_key()));
266  }
267 
268  //! Set the name and corresponding element and mass
269  void set_atom_type(AtomType t);
270 
271  //! get element
272  Element get_element() const {
273  return Element(get_particle()->get_value(get_element_key()));
274  }
275 #ifndef IMP_DOXYGEN
276  void set_element(Element e);
277 #endif
278 
279  double get_occupancy() const {
280  if (!get_particle()->has_attribute(get_occupancy_key())) {
281  return 1;
282  } else {
283  return get_particle()->get_value(get_occupancy_key());
284  }
285  }
286 
287  void set_occupancy(double occupancy) {
288  if (!get_particle()->has_attribute(get_occupancy_key())) {
289  get_particle()->add_attribute(get_occupancy_key(),occupancy);
290  } else {
291  get_particle()->set_value(get_occupancy_key(),occupancy);
292  }
293  }
294 
295  double get_temperature_factor() const {
296  if (!get_particle()->has_attribute(get_temperature_factor_key())) {
297  return 0;
298  } else {
299  return get_particle()->get_value(get_temperature_factor_key());
300  }
301  }
302 
303  void set_temperature_factor(double tempFactor) {
304  if (!get_particle()->has_attribute(get_temperature_factor_key())) {
305  get_particle()->add_attribute(get_temperature_factor_key(),tempFactor);
306  } else {
307  get_particle()->set_value(get_temperature_factor_key(),tempFactor);
308  }
309  }
310 
311  /** @name The atom index in the input file
312  This index is not necessarily unique over any particular
313  set of atoms and so should never be used as an atom identifier
314  except during I/O.
315  @{
316  */
317  IMP_DECORATOR_GET_SET_OPT(input_index, get_input_index_key(),
318  Int, Int, -1);
319  /* @}*/
320 
321  /** @name Keys
322  These methods provide access to the various keys used to store
323  things in the Atom. These can be used if you want to
324  use an attribute to search a set of particles.
325  @{
326  */
327  static IntKey get_atom_type_key();
328 
329  static IntKey get_element_key();
330 
331  static IntKey get_input_index_key();
332 
333  static FloatKey get_occupancy_key();
334 
335  static FloatKey get_temperature_factor_key();
336  //! @}
337 };
338 
339 IMP_DECORATORS(Atom,Atoms, Hierarchies);
340 
341 
342 #ifdef SWIG
343 class Residue;
344 #endif
345 
346 //! Return the Residue containing this atom
347 /** The atom must be part of a molecular hierarchy.
348 
349  \throw ValueException if no residue is found, unless
350  nothrow is true.
351 
352  \relatesalso Atom
353  \relatesalso Residue
354  \relatesalso Hierarchy
355  */
356 IMPATOMEXPORT Residue get_residue(Atom d, bool nothrow=false);
357 
358 //! Return a particle atom from the residue
359 /** The residue must be part of a molecular hierarchy.
360  \relatesalso Atom
361  \relatesalso Residue
362  \relatesalso Hierarchy
363  */
364 IMPATOMEXPORT Atom get_atom(Residue rd, AtomType at);
365 
366 
367 //! Create a new AtomType
368 /** This creates a new AtomType (returned) and sets up the mapping
369  between the AtomType and the proper element.
370  \note This method has not been tested. If you use it, please
371  write a test and remove this comment.
372  \relatesalso AtomType
373  \see atom_type_exists()
374 */
375 IMPATOMEXPORT AtomType add_atom_type(std::string name, Element e);
376 
377 IMPATOMEXPORT Element get_element_for_atom_type(AtomType at);
378 
379 //! Return true if that atom type already exists.
380 IMPATOMEXPORT bool get_atom_type_exists(std::string name);
381 
382 IMPATOM_END_NAMESPACE
383 
384 #endif /* IMPATOM_ATOM_H */