Rosetta 3.5
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
BuildInstruction.hh
Go to the documentation of this file.
1 // -*- mode:c++;tab-width:2;indent-tabs-mode:t;show-trailing-whitespace:t;rm-trailing-spaces:t -*-
2 // vi: set ts=2 noet:
3 //
4 // (c) Copyright Rosetta Commons Member Institutions.
5 // (c) This file is part of the Rosetta software suite and is made available under license.
6 // (c) The Rosetta software is developed by the contributing members of the Rosetta Commons.
7 // (c) For more information, see http://www.rosettacommons.org. Questions about this can be
8 // (c) addressed to University of Washington UW TechTransfer, email: license@u.washington.edu.
9 
10 /// @file protocols/forge/build/BuildInstruction.hh
11 /// @brief tracks modifications to be made and is capable of residue length changes on a Pose
12 /// @author Yih-En Andrew Ban (yab@u.washington.edu)
13 
14 #ifndef INCLUDED_protocols_forge_build_BuildInstruction_hh
15 #define INCLUDED_protocols_forge_build_BuildInstruction_hh
16 
17 // unit headers
19 
20 // package headers
22 
23 // project headers
24 #include <core/types.hh>
27 // AUTO-REMOVED #include <core/conformation/Conformation.fwd.hh>
30 #include <core/pose/Pose.fwd.hh>
31 
32 // utility headers
33 #include <utility/signals/Link.hh>
34 // AUTO-REMOVED #include <utility/vector1.hh>
35 
36 // C++ headers
37 #include <set>
38 #include <string>
39 
40 #include <utility/vector1.hh>
41 
42 
43 
44 namespace protocols {
45 namespace forge {
46 namespace build {
47 
48 
49 // enclose enum in descriptive namespace to prevent conflicts
50 namespace BuildInstructionState {
51  /// @brief describes the state of the BuildInstruction
52  /// @details There are currently three possible BuildInstruction states.
53  /// <em>READY</em> indicates the BuildInstruction has been reset and is
54  /// ready to modify a Pose. <em>WAITING_ON_DEPENDENCIES</em> indicates
55  /// the BuildInstruction is waiting for its dependencies to be satisfied
56  /// before allowing modifications to proceed. <em>MODIFY_WAS_SUCCESSFUL</em>
57  /// indicates the BuildInstruction has finished modifications to the Pose,
58  /// and its residue indexing is now consistent with the newly modified Pose.
59  enum Enum {
63  };
64 }
65 
66 
67 /// @brief tracks modifications to be made and is capable of making residue length changes on a Pose
69 
70 
71 private: // typedefs
72 
73 
75 
76 
77 public: // typedefs
78 
79 
80  typedef core::Size Size;
81  typedef core::Real Real;
87 
89 
90  typedef utility::signals::Link Link;
91 
92  typedef std::set< Size > Positions;
94 
95 
96 public: // construct/destruct
97 
98 
99  /// @brief default constructor
101 
102 
103  /// @brief interval constructor
104  /// @param[in] i the residue range to operate on
105  /// @param[in] rts the residue type set to use, default FA_STANDARD
107  Interval const & i,
109  );
110 
111 
112  /// @brief copy constructor
113  BuildInstruction( BuildInstruction const & rval );
114 
115 
116  /// @brief default destructor
117  virtual
119 
120 
121 public: // assignment
122 
123 
124  /// @brief copy assignment
125  BuildInstruction & operator =( BuildInstruction const & rval );
126 
127 
128 public: // virtual constructors
129 
130 
131  /// @brief clone this object
132  virtual
133  BuildInstructionOP clone() const = 0;
134 
135 
136 public: // Pose modification methods
137 
138 
139  /// @brief modify this pose
140  /// @return the state of the BuildInstruction
142 
143 
144 public: // query state
145 
146 
147  /// @brief return the state of this BuildInstruction
148  inline
150  return state_;
151  }
152 
153 
154  /// @brief Is the BuildInstruction's state at <em>READY</em>?
155  /// @remarks <em>READY</em> indicates the BuildInstruction has been reset
156  /// and is ready to modify a Pose.
157  bool ready() const;
158 
159 
160  /// @brief Is the BuildInstruction's state at <em>WAITING_ON_DEPENDENCIES</em>?
161  /// @remarks <em>WAITING_ON_DEPENDENCIES</em> indicates
162  /// the BuildInstruction is waiting for its dependencies to be satisfied
163  /// before allowing modifications to proceed.
164  bool waiting_on_dependencies() const;
165 
166 
167  /// @brief Is the BuildInstruction's state at <em>MODIFY_WAS_SUCCESSFUL</em>?
168  /// @remarks <em>MODIFY_WAS_SUCCESSFUL</em> indicates the BuildInstruction has
169  /// finished modifications to the Pose, and its residue indexing is now
170  /// consistent with the newly modified Pose.
171  bool modify_was_successful() const;
172 
173 
174 public: // virtual Conformation observer interface
175 
176 
177  /// @brief update indexing on residue append
178  virtual
179  void on_residue_append( LengthEvent const & event ) = 0;
180 
181 
182  /// @brief update indexing on residue prepend
183  virtual
184  void on_residue_prepend( LengthEvent const & event ) = 0;
185 
186 
187  /// @brief update indexing on residue delete
188  virtual
189  void on_residue_delete( LengthEvent const & event ) = 0;
190 
191 
192 public: // common Conformation observer interface
193 
194 
195  /// @brief attach to a Pose's conformation
196  void attach_to( Pose & pose );
197 
198 
199  /// @brief detach from a Pose's conformation
200  void detach_from();
201 
202 
203  /// @brief update any indexing wrt length change to Pose/Conformation being watched
204  void on_length_change( LengthEvent const & event );
205 
206 
207 public: // accessors
208 
209 
210  /// @brief detach after modify()?
211  /// @details Ordinarily a modify() call consists of attaching as a
212  /// length obs of the Pose, actually doing the modify, and then
213  /// detaching as a length obs of the Pose. This flag governs whether
214  /// the last detach occurs.
215  inline
216  bool detach_after_modify() const {
217  return detach_after_modify_;
218  }
219 
220 
221  /// @brief return original residue range of this instruction
222  inline
223  Interval const & original_interval() const {
224  return original_interval_;
225  }
226 
227 
228  /// @brief the residue type set being used
229  inline
231  return *rts_;
232  }
233 
234 
235  /// @brief does this BuildInstruction have dependencies?
236  inline
237  bool has_dependencies() const {
238  return !dependencies_.empty();
239  }
240 
241 
242  /// @brief the number of dependencies this BuildInstruction has
243  inline
245  return dependencies_.size();
246  }
247 
248 
249  /// @brief the list of instructions whose modify() must complete before
250  /// the modify() for this instruction may be called successfully
251  inline
253  return dependencies_;
254  }
255 
256 
257 public: // virtual accessors
258 
259 
260  /// @brief is the original interval storing valid information, or is empty
261  /// or being used for something else?
262  virtual
263  bool original_interval_valid() const = 0;
264 
265 
266  /// @brief a copy of the working range of residues specifying the modified region
267  /// @details This residue range can change wrt length changes in Pose /Conformation
268  /// being watched.
269  virtual
270  Interval interval() const = 0;
271 
272 
273  /// @brief return a copy of the set of positions within the new region
274  /// that were pre-existing in the original Pose prior to modify()
275  virtual
276  Positions preexisting_positions() const = 0;
277 
278 
279  /// @brief return a copy of the set of positions that are "new" and did
280  /// not exist in the original Pose.
281  virtual
282  Positions new_positions() const = 0;
283 
284 
285  /// @brief return a copy of the set of positions within the newly modified
286  /// region that has a defined conformation. E.g. existing or copied residues.
287  /// @details This set can change wrt length changes in Pose/Conformation being
288  /// watched.
289  virtual
290  Positions defined_positions() const = 0;
291 
292 
293  /// @brief return a copy of the set of positions within the newly modified
294  /// region that has an undefined conformation. E.g. newly created residues.
295  /// @details This set can change wrt length changes in Pose/Conformation being
296  /// watched.
297  virtual
298  Positions undefined_positions() const = 0;
299 
300 
301  /// @brief return a copy of the MoveMap that defines the moveable/fixed
302  /// positions/dofs for this instruction
303  /// @details This set can change wrt length changes in Pose/Conformation being
304  /// watched.
305  virtual
306  MoveMap movemap() const = 0;
307 
308 
309 public: // mutators
310 
311 
312  /// @brief set detach after modify()
313  /// @details Ordinarily a modify() call consists of attaching as a
314  /// length obs of the Pose, actually doing the modify, and then
315  /// detaching as a length obs of the Pose. This flag governs whether
316  /// the last detach occurs.
317  inline
318  void detach_after_modify( bool const flag ) {
319  detach_after_modify_ = flag;
320  }
321 
322 
323  /// @brief reset intervals, positions, etc to initial state and drop
324  /// observers. State set to READY.
325  void reset_accounting();
326 
327 
328 public: // virtual mutators
329 
330 
331  /// @brief add an instruction to this BuildInstruction's dependency list
332  /// @remarks before this instruction's modify() may complete properly, all
333  /// instructions in the dependency list must have completed modify() first
334  virtual
336 
337 
338  /// @brief is this instruction dependent upon the given instruction?
339  virtual
340  bool dependent_on( BuildInstructionCAP i ) const;
341 
342 
343  /// @brief clear the list of dependencies
344  inline
346  dependencies_.clear();
347  }
348 
349 
350 public: // original positions
351 
352 
353  /// @brief return the set of positions within the original interval that
354  /// will be kept in this BuildInstruction
355  virtual
357 
358 
359  /// @brief return set of positions within the original interval that will
360  /// be deleted in this BuildInstruction
361  virtual
363 
364 
365 public: // instruction comparison
366 
367 
368  /// @brief compares fixed and mutable positions to determine compatibility with
369  /// another instruction
370  /// @remarks override this to obtain custom compatibility check
371  virtual
372  bool compatible_with( BuildInstruction const & rval ) const;
373 
374 
375  /// @brief return set of any fixed positions necessary with respect to the original
376  /// interval and original Pose numbering
377  /// @remarks Used for ensuring build regions for instructions do not overlap and
378  /// so that jumps may be placed correctly.
379  /// @return empty set if no fixed positions necessary
380  virtual
382 
383 
384  /// @brief return set of any mutable positions necessary with respect to the original
385  /// interval and original Pose numbering
386  /// @remarks Used for ensuring build regions for instructions do not overlap and
387  /// so that jumps may be placed correctly.
388  virtual
390 
391 
392 public: // virtual object descriptor
393 
394 
395  /// @brief does this object create undefined backbone in the modified region?
396  virtual
397  bool creates_undefined_backbone() const = 0;
398 
399 
400 protected: // accessors
401 
402 
403  /// @brief access to the Conformation length observer link
404  inline
405  Link const & length_obs_link() const {
406  return length_obs_link_;
407  }
408 
409 
410 protected: // dependency handling
411 
412 
413  /// @brief are dependencies satisfied so that modify_impl() can complete
414  /// successfully?
415  /// @return True if modify_impl() can be called, False otherwise.
416  /// @remarks This function will automatically be checked within modify()
417  /// prior to running modify_impl().
418  virtual
419  bool dependencies_satisfied() const;
420 
421 
422 protected: // virtual Pose modification methods
423 
424 
425  /// @brief do the actual work of modifying the Pose
426  virtual
427  void modify_impl( Pose & pose ) = 0;
428 
429 
430 protected: // set state
431 
432 
433  /// @brief set the BuildInstruction's current state
434  inline
436  state_ = s;
437  }
438 
439 
440 protected: // virtual mutators
441 
442 
443  /// @brief do the actual reset of intervals, positions, etc to initial state
444  virtual
445  void reset_accounting_impl() = 0;
446 
447 
448 private: // data
449 
450 
451  /// @brief Describes the state of the BuildInstruction.
452  /// @remarks See documentation of BuildInstructionState::Enum and the
453  /// query state, set state, and <tt>modify()</tt> functions for more
454  /// information.
456 
457 
458  /// @brief defines the original residue range via closed interval [first, second]
459  /// or an original anchor position [anchor, anchor] that's marked as invalid
460  /// @remarks no mutable access to this data
462 
463 
464  /// @brief the residue type set to use
466 
467 
468  /// @brief Conformation length observer link
470 
471 
472  /// @brief detach after performing modify()
473  /// @details Ordinarily a modify() call consists of attaching as a
474  /// length obs of the Pose, actually doing the modify, and then
475  /// detaching as a length obs of the Pose. This flag governs whether
476  /// the last detach occurs.
478 
479 
480  /// @brief if this BuildInstruction's modify() is dependent on any other
481  /// BuildInstructions whose modify() must complete first, we store access
482  /// to those instructions here
483  /// @warning Due to copy ambiguities, dependencies are currently not copied!
484  /// They must be externally rebuilt, e.g. by the BuildManager.
486 
487 
488 };
489 
490 
491 } // namespace build
492 } // namespace forge
493 } // namespace protocols
494 
495 
496 #endif /* INCLUDED_protocols_forge_build_BuildInstruction_HH */