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