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