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