IMP  2.0.0
The Integrative Modeling Platform
charmm_segment_topology.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/charmm_segment_topology.h
3  * \brief Classes for handling CHARMM-style topology of segments.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPATOM_CHARMM_SEGMENT_TOPOLOGY_H
10 #define IMPATOM_CHARMM_SEGMENT_TOPOLOGY_H
11 
12 #include "IMP/Object.h"
13 #include "Hierarchy.h"
14 #include <IMP/atom/atom_config.h>
15 #include "charmm_topology.h"
16 #include "CHARMMParameters.h"
17 
18 IMPATOM_BEGIN_NAMESPACE
19 
20 //! The topology of a single CHARMM segment in a model.
21 /** CHARMM segments typically correspond to IMP::atom::Chain particles.
22  */
23 class IMPATOMEXPORT CHARMMSegmentTopology : public IMP::base::Object {
24  /** @name Residues
25 
26  The segment contains a chain of residues.
27  */
28  /**@{*/
29  IMP_LIST_ACTION(public, CHARMMResidueTopology,CHARMMResidueTopologies,
30  residue, residues, CHARMMResidueTopology*,
31  CHARMMResidueTopologies, obj->set_was_used(true),,);
32  /**@}*/
33 
35 public:
36  CHARMMSegmentTopology(std::string name = "CHARMM segment topology %1%")
37  : Object(name) {}
38 
39  //! Apply patches to the first and last residue in the segment.
40  /** Default patches are defined for each residue type in the topology
41  file. For example, segments containing amino acids will by default
42  apply the CTER and NTER patches to the C and N termini, respectively.
43  */
44  void apply_default_patches(const CHARMMParameters *ff);
45 };
46 
48 
49 //! The topology of a complete CHARMM model.
50 /** This defines all of the segments (chains) in the model as
51  CHARMMSegmentTopology objects, which in turn define the list of residues,
52  the atoms in each residue, and their types and the connectivity
53  between them.
54 
55  A CHARMMTopology object can be created manually, in which case add_segment()
56  can be called to add individual CHARMMSegmentTopology objects. In this way
57  a new topology can be created, e.g. from protein primary sequence.
58 
59  Alternatively, given an existing Hierarchy, e.g. as returned from
60  read_pdb(), CHARMMParameters::create_topology() can be called to generate
61  a new topology that corresponds to the primary sequence of the Hierarchy.
62 
63  A new topology can be patched (apply_default_patches() or
64  CHARMMPatch::apply()) to modify the simple chain of residues to
65  account for modified residues, C- or N-termini special cases, disulfide
66  bridges, etc.
67 
68  Once a topology is created, it can be used to generate new particles
69  which conform to that topology (create_hierarchy()), or to add
70  topology information to an existing Hierarchy (e.g. add_atom_types(),
71  add_bonds(), add_charges()).
72  */
73 class IMPATOMEXPORT CHARMMTopology : public IMP::base::Object {
74  Pointer<const CHARMMParameters> force_field_;
75  WarningContext warn_context_;
76  typedef std::map<const CHARMMResidueTopology *, Hierarchy> ResMap;
77 
78  void map_residue_topology_to_hierarchy(Hierarchy hierarchy,
79  ResMap &resmap) const;
80 public:
81  CHARMMTopology(const CHARMMParameters *force_field,
82  std::string name = "CHARMM topology %1%")
83  : Object(name), force_field_(force_field) {
84  set_was_used(true);
85  }
86 
87  const CHARMMParameters *get_parameters() { return force_field_; }
88 
89  //! Add a sequence (as a string of one-letter codes) to the topology.
90  /** The sequence can contain amino-acid one-letter codes and '/' characters
91  to denote the start of a new segment. The empty string simply adds a new
92  segment that contains no residues.
93  \exception ValueException if an invalid one-letter code is passed.
94  */
95  void add_sequence(std::string sequence);
96 
97  //! Call CHARMMSegmentTopology::apply_default_patches() for all segments.
99  for (unsigned int i = 0; i < get_number_of_segments(); ++i) {
100  get_segment(i)->apply_default_patches(force_field_);
101  }
102  }
103 
104  //! Create a new Hierarchy in the given model using this topology.
105  /** The hierarchy contains chains, residues and atoms as defined in the
106  topology. Note, however, that none of the generated atoms is given
107  coordinates.
108  Chains are labeled 'A', 'B' etc. Residues are numbered from 1 within
109  each chain.
110  \see add_coordinates.
111  */
112  Hierarchy create_hierarchy(Model *model) const;
113 
114  //! Add CHARMM atom types to the given Hierarchy using this topology.
115  /** The primary sequence of the Hierarchy must match that of the topology.
116  \see CHARMMAtom.
117  */
118  void add_atom_types(Hierarchy hierarchy) const;
119 
120  //! Add atom Cartesian coordinates to the given Hierarchy using this topology.
121  /** The primary sequence of the Hierarchy must match that of the topology.
122 
123  This method can be used to add missing coordinates (e.g. of hydrogens
124  or sidechains, such as those added by add_missing_atoms()), or to
125  generate a starting conformation for a new Hierarchy (e.g. generated
126  by create_hierarchy()). On exit, all atoms will have coordinates.
127 
128  - Cartesian coordinates for any atoms that are not currently core::XYZ
129  particles are generated using internal coordinates that relate them
130  to particles that do have XYZ coordinates.
131 
132  - For each segment (chain), if no atoms have coordinates but a triplet
133  of atoms can be found where theit internal distances and angle can be
134  determined from internal coordinates, these three atoms will be
135  placed to seed the generation procedure. For the first segment, the
136  atoms will be placed on the xy plane with the first atom at the origin.
137  For subsequent segments, the first atom is placed offset by (2.,2.,2.)
138  from the last atom in the previous segment.
139 
140  - If any atoms cannot be placed using either method, their coordinates
141  are assigned randomly to lie near atoms that are near in sequence or,
142  if no such atoms exist, near the segment origin.
143 
144  \note It is valid to specify internal coordinates in a CHARMM topology
145  file that leave the angles or distances unspecified. This function
146  will attempt to fill in this missing information using CHARMM atom
147  types and the parameter file. Thus, better results will be obtained
148  if add_atom_types() is called before this function, and the
149  CHARMMParameters object used contains parameter information.
150  */
151  void add_coordinates(Hierarchy hierarchy) const;
152 
153  //! Add any missing atoms to the given Hierarchy using this topology.
154  /** Missing atoms are defined as those present in the topology but not
155  in the hierarchy.
156  Newly-added atoms are assigned CHARMM types, but no coordinates
157  (use add_coordinates() to add them).
158  The primary sequence of the Hierarchy must match that of the topology.
159  \see CHARMMAtom, remove_charmm_untyped_atoms, add_coordinates.
160  */
161  void add_missing_atoms(Hierarchy hierarchy) const;
162 
163  //! Make the Hierarchy conform with this topology.
164  /** The hierarchy is modified if necessary so that each residue contains
165  the same set of atoms as defined in the CHARMM topology, and any
166  atoms missing coordinates are assigned them.
167 
168  This is equivalent to calling add_atom_types(), add_missing_atoms(),
169  remove_charmm_untyped_atoms(), and add_coordinates() in that order.
170  */
171  void setup_hierarchy(Hierarchy hierarchy) const;
172 
173  //! Add CHARMM charges to the given Hierarchy using this topology.
174  /** The primary sequence of the Hierarchy must match that of the topology.
175  \see Charged.
176  */
177  void add_charges(Hierarchy hierarchy) const;
178 
179  //! Add bonds to the given Hierarchy using this topology, and return them.
180  /** The primary sequence of the Hierarchy must match that of the topology.
181  Parameters for the bonds (ideal bond length, force constant) are
182  extracted from the CHARMM parameter file, using the types of each atom
183  (add_atom_types() must be called first, or the particles otherwise
184  manually typed using CHARMMAtom::set_charmm_type()).
185 
186  If no parameters are defined for a given bond, the bond is created
187  with zero stiffness, such that the bond can still be excluded from
188  nonbonded interactions but BondSingletonScore will not score it.
189 
190  Note that typically CHARMM defines bonds and impropers
191  (see add_impropers()) but angles and dihedrals are auto-generated from
192  the existing bond graph (see CHARMMParameters::create_angles() and
193  CHARMMParameters::create_dihedrals()).
194 
195  The list of newly-created Bond particles can be passed to a
196  StereochemistryPairFilter to exclude bonded particles from nonbonded
197  interactions, or to a BondSingletonScore to score each bond.
198 
199  \return a list of the generated Bond decorators.
200  */
201  Particles add_bonds(Hierarchy hierarchy) const;
202 
203  //! Add dihedrals to the given Hierarchy using this topology, and return them.
204  /** The primary sequence of the Hierarchy must match that of the topology.
205 
206  Typically, dihedrals are auto-generated from the existing bond
207  graph (see CHARMMParameters::create_dihedrals()) rather than using
208  this function.
209 
210  \return a list of the generated Dihedral decorators.
211 
212  \see add_bonds().
213  */
214  Particles add_dihedrals(Hierarchy hierarchy) const;
215 
216  //! Add impropers to the given Hierarchy using this topology, and return them.
217  /** The primary sequence of the Hierarchy must match that of the topology.
218 
219  The list of newly-created Dihedral particles can be passed to a
220  ImproperSingletonScore to score each improper dihedral.
221 
222  \return a list of the generated Dihedral decorators.
223 
224  \see add_bonds().
225  */
226  Particles add_impropers(Hierarchy hierarchy) const;
227 
228  /** @name Segments
229 
230  The topology contains a list of segments, one for each chain.
231  */
232  /**@{*/
233  IMP_LIST_ACTION(public, CHARMMSegmentTopology, CHARMMSegmentTopologies,
234  segment, segments, CHARMMSegmentTopology*,
235  CHARMMSegmentTopologies, obj->set_was_used(true),,);
236  /**@}*/
237 
239 };
241 
242 IMPATOM_END_NAMESPACE
243 
244 #endif /* IMPATOM_CHARMM_SEGMENT_TOPOLOGY_H */