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