IMP: Atom.h Source File

00001 /**
00002  *  \file atom/Atom.h     \brief Simple atom decorator.
00003  *
00004  *  Copyright 2007-2010 IMP Inventors. All rights reserved.
00005  *
00006  */
00007 
00008 #ifndef IMPATOM_ATOM_H
00009 #define IMPATOM_ATOM_H
00010 
00011 #include "atom_config.h"
00012 #include "atom_macros.h"
00013 #include "Residue.h"
00014 #include "Hierarchy.h"
00015 #include "element.h"
00016 #include <IMP/core/utility.h>
00017 #include <IMP/core/XYZ.h>
00018 #include <IMP/core/core_macros.h>
00019 
00020 #include <IMP/base_types.h>
00021 #include <IMP/Particle.h>
00022 #include <IMP/Model.h>
00023 
00024 #include <vector>
00025 #include <deque>
00026 
00027 IMPATOM_BEGIN_NAMESPACE
00028 
00029 IMP_DECLARE_CONTROLLED_KEY_TYPE(AtomType, IMP_ATOM_TYPE_INDEX);
00030 /** \class AtomType
00031     \brief The type of an atom.
00032 
00033     The standard Atom names in %IMP are derived from the PDB names as follows:
00034     - the AtomType of a protein, DNA or RNA atom is the AtomType
00035     created from the PDB atom name string with spaces removed. For
00036     example, a protein C-alpha has the name AtomType("CA").
00037     - the AtomType for a heterogen atom is the AtomType created by
00038     prefixing "HET:" to the PBD atom name string (this time without
00039     spaces removed). For example, a calcium atom is AtomType("HET:CA  ").
00040 
00041     We provide an AtomType instance for each of the standard PDB %atom types.
00042     These have names such as IMP::atom::AT_N. The full list is elided for
00043     readability.
00044 
00045     An AtomType implies an element (and hence a mass). While we have the
00046     associations set up for protein, DNA and RNA atoms, it may be necessary
00047     to add them for heterogen atoms. You can use the add_atom_type() function
00048     to do this.
00049 
00050     All atoms have the mass stored internally using a Mass decorator.
00051 
00052     \see IMP::atom::Atom
00053 */
00054 
00055 /* each static must be on a separate line because of MSVC bug C2487:
00056    see http://support.microsoft.com/kb/127900/
00057 */
00058 /** \relatesalso AtomType */
00059 IMPATOMEXPORT extern const AtomType AT_UNKNOWN;
00060 /** \relatesalso AtomType */
00061 IMPATOMEXPORT extern const AtomType AT_N;
00062 /** \relatesalso AtomType */
00063 IMPATOMEXPORT extern const AtomType AT_CA;
00064 #ifndef IMP_DOXYGEN
00065 /** \relatesalso AtomType */
00066 IMPATOMEXPORT extern const AtomType AT_C;
00067 /** \relatesalso AtomType */
00068 IMPATOMEXPORT extern const AtomType AT_O;
00069 /** \relatesalso AtomType */
00070 IMPATOMEXPORT extern const AtomType AT_H;
00071 /** \relatesalso AtomType */
00072 IMPATOMEXPORT extern const AtomType AT_H1;
00073 /** \relatesalso AtomType */
00074 IMPATOMEXPORT extern const AtomType AT_H2;
00075 /** \relatesalso AtomType */
00076 IMPATOMEXPORT extern const AtomType AT_H3;
00077 /** \relatesalso AtomType */
00078 IMPATOMEXPORT extern const AtomType AT_HA;
00079 /** \relatesalso AtomType */
00080 IMPATOMEXPORT extern const AtomType AT_HA1;
00081 /** \relatesalso AtomType */
00082 IMPATOMEXPORT extern const AtomType AT_HA2;
00083 /** \relatesalso AtomType */
00084 IMPATOMEXPORT extern const AtomType AT_CB;
00085 /** \relatesalso AtomType */
00086 IMPATOMEXPORT extern const AtomType AT_HB;
00087 /** \relatesalso AtomType */
00088 IMPATOMEXPORT extern const AtomType AT_HB1;
00089 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HB2;
00090 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HB3;
00091 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OXT;
00092 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CH3;
00093 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG;
00094 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG1;
00095 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CG2;
00096 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG;
00097 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG1;
00098 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG2;
00099 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG3;
00100 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG11;
00101 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG21;
00102 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG31;
00103 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG12;
00104 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG22;
00105 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HG32;
00106 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OG;
00107 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OG1;
00108 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_SG;
00109 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD;
00110 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD1;
00111 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CD2;
00112 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD;
00113 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD1;
00114 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD2;
00115 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD3;
00116 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD11;
00117 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD21;
00118 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD31;
00119 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD12;
00120 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD22;
00121 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HD32;
00122 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_SD;
00123 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OD1;
00124 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OD2;
00125 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_ND1;
00126 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_ND2;
00127 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE;
00128 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE1;
00129 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE2;
00130 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CE3;
00131 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE;
00132 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE1;
00133 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE2;
00134 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE3;
00135 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE21;
00136 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HE22;
00137 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OE1;
00138 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OE2;
00139 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE;
00140 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE1;
00141 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NE2;
00142 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ;
00143 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ2;
00144 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CZ3;
00145 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NZ;
00146 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ;
00147 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ1;
00148 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ2;
00149 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HZ3;
00150 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_CH2;
00151 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NH1;
00152 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_NH2;
00153 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OH;
00154 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH;
00155 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH11;
00156 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH21;
00157 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH2;
00158 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH12;
00159 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH22;
00160 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH13;
00161 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH23;
00162 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HH33;
00163 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_P;
00164 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OP1;
00165 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_OP2;
00166 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O5p;
00167 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C5p;
00168 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5p;
00169 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5pp;
00170 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C4p;
00171 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H4p;
00172 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O4p;
00173 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C1p;
00174 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H1p;
00175 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C3p;
00176 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H3p;
00177 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O3p;
00178 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C2p;
00179 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H2p;
00180 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H2pp;
00181 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2p;
00182 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_HO2p;
00183 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N9;
00184 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C8;
00185 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H8;
00186 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N7;
00187 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C5;
00188 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C4;
00189 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N3;
00190 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C2;
00191 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N1;
00192 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C6;
00193 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N6;
00194 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H61;
00195 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H62;
00196 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O6;
00197 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N2;
00198 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H21;
00199 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H22;
00200 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H6;
00201 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H5;
00202 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O2;
00203 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_N4;
00204 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H41;
00205 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H42;
00206 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_O4;
00207 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_C7;
00208 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H71;
00209 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H72;
00210 /** \relatesalso AtomType */ IMPATOMEXPORT extern const AtomType AT_H73;
00211 #endif
00212 
00213 
00214 //! A decorator for a particle representing an atom.
00215 /**
00216    \ingroup hierarchy
00217    \see Hierarchy
00218  */
00219 class IMPATOMEXPORT Atom:
00220   public Hierarchy
00221 {
00222 public:
00223 
00224   IMP_DECORATOR(Atom, Hierarchy);
00225 
00226   Particle* get_particle() const {
00227     return Hierarchy::get_particle();
00228   }
00229 
00230   /** Create a decorator with the passed type and coordinates.*/
00231   static Atom setup_particle(Particle *p, AtomType t);
00232 
00233   /** Create a decorator by copying from o.*/
00234   static Atom setup_particle(Particle *p, Atom o);
00235 
00236   //! return true if the particle has the needed attributes
00237   static bool particle_is_instance(Particle *p) {
00238     return p->has_attribute(get_atom_type_key())
00239       && Hierarchy::particle_is_instance(p);
00240   }
00241 
00242   AtomType get_atom_type() const {
00243     return AtomType(get_particle()->get_value(get_atom_type_key()));
00244   }
00245 
00246   //! Set the name and corresponding element and mass
00247   void set_atom_type(AtomType t);
00248 
00249   Element get_element() const {
00250     return Element(get_particle()->get_value(get_element_key()));
00251   }
00252 
00253   /** @name The atom index in the input file
00254       This index is not necessarily unique over any particular
00255       set of atoms and so should never be used as an atom identifier
00256       except during I/O.
00257       @{
00258   */
00259   IMP_DECORATOR_GET_SET_OPT(input_index, get_input_index_key(),
00260                             Int, Int, -1);
00261   /* @}*/
00262 
00263   /** @name Keys
00264       These methods provide access to the various keys used to store
00265       things in the Atom. These can be used if you want to
00266       use an attribute to search a set of particles.
00267       @{
00268    */
00269   static IntKey get_atom_type_key();
00270 
00271   static IntKey get_element_key();
00272 
00273   static IntKey get_input_index_key();
00274   //! @}
00275 };
00276 
00277 IMP_OUTPUT_OPERATOR(Atom);
00278 
00279 IMP_DECORATORS(Atom, Hierarchies);
00280 /** \decorators{Atom}
00281 */
00282 /** \decoratorstemp{Atom}
00283 */
00284 
00285 
00286 #ifdef SWIG
00287 class Residue;
00288 #endif
00289 
00290 //! Return the Residue containing this atom
00291 /** The atom must be part of a molecular hierarchy.
00292 
00293     \throw ValueException if no residue is found, unless
00294     nothrow is true.
00295 
00296     \relatesalso Atom
00297     \relatesalso Residue
00298     \relatesalso Hierarchy
00299  */
00300 IMPATOMEXPORT Residue get_residue(Atom d, bool nothrow=false);
00301 
00302 //! Return a particle atom from the residue
00303 /** The residue must be part of a molecular hierarchy.
00304     \relatesalso Atom
00305     \relatesalso Residue
00306     \relatesalso Hierarchy
00307  */
00308 IMPATOMEXPORT Atom get_atom(Residue rd, AtomType at);
00309 
00310 
00311 //! Create a new AtomType
00312 /** This creates a new AtomType (returned) and sets up the mapping
00313     between the AtomType and the proper element.
00314     \note This method has not been tested. If you use it, please
00315     write a test and remove this comment.
00316     \relatesalso AtomType
00317     \see atom_type_exists()
00318 */
00319 IMPATOMEXPORT AtomType add_atom_type(std::string name, Element e);
00320 
00321 //! Return true if that atom type already exists.
00322 IMPATOMEXPORT bool get_atom_type_exists(std::string name);
00323 
00324 IMPATOM_END_NAMESPACE
00325 
00326 #endif  /* IMPATOM_ATOM_H */