IMP logo
IMP Reference Guide  2.14.0
The Integrative Modeling Platform
FGChain.h
Go to the documentation of this file.
1 /**
2  * \file FGChain.h
3  * \brief creating TAMD chains
4  *
5  * Copyright 2007-2020 IMP Inventors. All rights reserved.
6  */
7 
8 //TODO: turn FGChain, TAMDChain onto a Decorator? seems to make sense
9 //TODO: use "Representation" decorator?
10 
11 #ifndef IMPNPCTRANSPORT_FG_CHAIN_H
12 #define IMPNPCTRANSPORT_FG_CHAIN_H
13 
14 #include "npctransport_config.h"
16 #include "npctransport_proto.fwd.h"
17 //#include "internal/npctransport.pb.h"
18 
19 #include <IMP/atom/Hierarchy.h>
20 #include <IMP/PairScore.h>
21 #include <IMP/Object.h>
22 #include <IMP/nullptr.h>
24 #include <IMP/display/Color.h>
25 
26 
27 IMPNPCTRANSPORT_BEGIN_NAMESPACE
28 
29 class SimulationData;
30 class Scoring;
31 
32 /**
33  a chain with a root
34 
35  root - root of hierarchy
36  beads - fine chain particles
37 */
38 class IMPNPCTRANSPORTEXPORT FGChain : public IMP::Object {
39 public:
40  private:
41  // the root particle in the chain hierarchy
43 
44  // the restraint on the chain bonds
45  PointerMember<Restraint> bonds_restraint_;
46 
47  // the score used by bonds_restraint_; (has to be object cause pair score and singleton score do not derive from same class)
48  PointerMember<Object> bonds_score_;
49 
50  // chain bond force coefficient in kcal/mol/A or kcal/mol/A^2
51  // (depending on whether the bond is linear or harmonic)
52  double backbone_k_;
53 
54  // the rest length of a bond in the chain relative to the
55  // sum of the radii of the bonded spheres
56  double rest_length_factor_;
57 
58 
59  private:
60 
61  // TODO: this currently cannot work for more than two calls cause of
62  // ExclusiveConsecutivePairContainer - will need to switch to
63  // ConsecutivePairContainer or make a different design to solve this
64  /** recreate the bonds restraint for the chain beads based on the
65  current chain topology
66  */
67  void update_bonds_restraint(Scoring const* scoring_manager);
68 
69  public:
70 
71  /** initialized an FG chain with given backbone k and rest length factor,
72  and a specified root whose leaves are the beads of the chain.
73 
74  @param root root of the chain (leaves are assumed beads).
75  can be null = to be added later
76  @param backbone_k force constant between consecutive chain beads
77  @param rest_length_factor equilibrium distance factor between
78  consecutive beads relative to the sum of their radii
79  @param name chain object name
80 
81  \see LinearWellPairScore
82  */
84  double backbone_k = 0.0,
85  double rest_length_factor = 1.0,
86  std::string name = "chain %1%")
87  : Object(name),
88  root_(root),
89  bonds_restraint_(nullptr),
90  bonds_score_(nullptr),
91  backbone_k_(backbone_k),
92  rest_length_factor_(rest_length_factor)
93  {
94  IMP_USAGE_CHECK(rest_length_factor>0.0, "bonds rest length factor" <<
95  " should be positive");
96  }
97 
99  { return atom::Hierarchy(root_); }
100 
101  protected:
102  /** set the root of the chain to this particle
103  with the beads being the leaves of Hierarchy(p)
104 
105  @note it is assumed that p is decorated as atom::Hiererachy
106  */
107  void set_root(Particle* p){
108  IMP_USAGE_CHECK(atom::Hierarchy::get_is_setup(p),
109  "root must be Hierarchy decorated");
110  root_ = p;
111  }
112 
113  /** set the root of the chain to this particle
114  with the beads being the leaves of Hierarchy(p)
115  */
117  root_ = root.get_particle();
118  }
119 
120 
121 
122  public:
123 
124  //! get the beads of the chain (assume valid root)
126  { return core::get_leaves(get_root()); }
127 
128  //! get the i'th bead in the chain (assume valid root)
129  IMP::Particle* get_bead(unsigned int i) const
130  { return get_beads()[i]; }
131 
132  //! get the i'th bead index in the chain (assume valid root)
133  IMP::ParticleIndex get_bead_index(unsigned int i) const
134  { return get_beads()[i]->get_index(); }
135 
136  //! get the number of beads in the chain (assume valid root)
137  unsigned int get_number_of_beads() const
138  { return get_beads().size(); }
139 
140  /**
141  Returns a restraint associated with internal interactions by this chain.
142  Once this method has been called once, it is assumed that the
143  chain topology remains static (the behavior of the restraint
144  if the chain topology changes is undefined, e.g. if beads are added)
145 
146  @note this restraint is affected by future calls to set_rest_length_factor()
147  and set_backbone_k(). However, it applies only to the topology of the chain
148  at the time of call, if the chain topology changes, this methods should be
149  called again.
150 
151  @note assumes that the chain has a valid root whose leaves are beads
152  */
153  virtual Restraints get_chain_restraints(Scoring const* scoring_manager);
154 
155  /** set the equilibrium distance factor between consecutive beads
156  relative to the sum of their radii
157 
158  @note This affects also restraints previously returned by
159  get_chain_restraints()
160 
161  \see LinearWellPairScore
162  \see HarmonicSpringSingletonScore
163  \see RelaxingSpring
164  */
165  void set_rest_length_factor(double rlf);
166 
167  /** set the force constant between consecutive chain beads
168 
169  @note This affects also restraints previously returned by
170  get_chain_restraints()
171 
172  \see LinearWellPairScore
173  */
174  void set_backbone_k(double k);
175 
176  //! get the equilibrium distance factor between consecutive beads relative
177  //! to the sum of their radii
178  double get_rest_length_factor() const{
179  return rest_length_factor_;
180  }
181 
182  //! get the force constant between consecutive chain beads
183  double get_backbone_k() const {
184  return backbone_k_;
185  }
186 
188 };
189 
191 
192 
193 /****************** utility methods ***************/
194 
195 /**
196  Create a chain particle hierarchy, to be owned by the model of sd,
197  with restraint bonding consecutive particles added to sd, according to the
198  parameters specified in fg_data.
199 
200  Notes:
201 
202  The type of the chain root is specified in fg_data.type(). Individual
203  particles may have different types if fg_data.type_suffix_list is non-empty.
204  In this case, the type of particle i is suffixed with fg_data.type_suffix_list[i],
205  or remains fg_data.type() if the suffix is "".
206 
207  The rest length between two consecutive chain beads is
208  fg_data.radius() * 2.0 * fg_data.rest_length_factor() and the
209  spring constant is the simulation backbone_k parameter.
210 
211  If fg_data.is_tamd() is true, created a TAMD hierarchy, otherwise
212  a simple parent + beads structure. In the TAMD case, the custom restraint
213  are added to sd->get_scoring() and the tamd images are added to sd->root()
214 
215  @param[in,out] sd the simulation data whose model is associated with the
216  new chain. The chain is also added to the simulation data
217  scoring object.
218  @param parent parent hierarchy to which chain is added
219  @param[in] fg_data data about the FG chain
220  @param[in] c color of chain particles
221 
222  @return chain structure (with root and chain beads)
223 
224  */
225 IMPNPCTRANSPORTEXPORT
228  atom::Hierarchy parent,
229  const ::npctransport_proto::Assignment_FGAssignment &fg_data,
230  display::Color c );
231 
232 
233 /**
234  gets a newly allocated chain structure from a root of an FG nup
235  (by adding its ordered leaves)
236 */
237 IMPNPCTRANSPORTEXPORT
239 
240 /**
241  gets a newly allocated chain structure from a root of an FG nup
242  (by adding its ordered leaves)
243 
244  @param p_root a particle that is assumed to be
245  Hierarchy decorated
246  */
247 IMPNPCTRANSPORTEXPORT
248 FGChain* get_fg_chain(Particle* p_root);
249 
250 IMPNPCTRANSPORT_END_NAMESPACE
251 
252 #endif /* IMPNPCTRANSPORT_FG_CHAIN_H */
Represent an RGB color.
Definition: Color.h:24
Return all pairs from a SingletonContainer.
FGChain * create_fg_chain(IMP::npctransport::SimulationData *sd, atom::Hierarchy parent, const ::npctransport_proto::Assignment_FGAssignment &fg_data, display::Color c)
unsigned int get_number_of_beads() const
get the number of beads in the chain (assume valid root)
Definition: FGChain.h:137
FGChain * get_fg_chain(Particle *p_root)
double get_rest_length_factor() const
Definition: FGChain.h:178
IMP::Particle * get_bead(unsigned int i) const
get the i'th bead in the chain (assume valid root)
Definition: FGChain.h:129
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
FGChain(IMP::Particle *root, double backbone_k=0.0, double rest_length_factor=1.0, std::string name="chain %1%")
Definition: FGChain.h:83
IMP::ParticlesTemp get_beads() const
get the beads of the chain (assume valid root)
Definition: FGChain.h:125
GenericHierarchies get_leaves(Hierarchy mhd)
Get all the leaves of the bit of hierarchy.
double get_backbone_k() const
get the force constant between consecutive chain beads
Definition: FGChain.h:183
Decorator for helping deal with a hierarchy of molecules.
Scoring associated with a SimulationData object.
Definition: Scoring.h:47
Provide a nullptr keyword analog.
The standard decorator for manipulating molecular structures.
Common base class for heavy weight IMP objects.
Definition: Object.h:106
Define PairScore.
void set_root(atom::Hierarchy root)
Definition: FGChain.h:116
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:146
Represent a color.
Particle * get_particle() const
Returns the particle decorated by this decorator.
Definition: Decorator.h:171
Store all parameters for a simulation.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
void set_root(Particle *p)
Definition: FGChain.h:107
A shared base class to help in debugging and things.
Hierarchy get_root(Hierarchy h)
Return the root of the hierarchy.
Class to handle individual particles of a Model object.
Definition: Particle.h:41
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
A Score on the distance between a pair of particles.
const std::nullptr_t nullptr
Definition: nullptr.h:27
IMP::ParticleIndex get_bead_index(unsigned int i) const
get the i'th bead index in the chain (assume valid root)
Definition: FGChain.h:133
forward declaration of incomplete protobuf files for the main data structures used ...