IMP  2.0.0
The Integrative Modeling Platform
subset_graphs.h
Go to the documentation of this file.
1 /**
2  * \file IMP/domino/subset_graphs.h
3  * \brief A beyesian infererence-based sampler.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPDOMINO_SUBSET_GRAPHS_H
10 #define IMPDOMINO_SUBSET_GRAPHS_H
11 
12 #include "particle_states.h"
13 #include "Subset.h"
14 #include <IMP/ScoringFunction.h>
16 #include <boost/graph/adjacency_list.hpp>
17 
18 
19 IMPDOMINO_BEGIN_NAMESPACE
20 
21 /** An undirected graph on subsets of vertices. Each vertex is
22  named with an Subset.
23  */
24 IMP_GRAPH(SubsetGraph, undirected, Subset, int);
25 
26 
27 /** An undirected graph with one vertex per particle of interest.
28  Two particles are connected by an edge if a Restraint
29  or ScoreState creates and interaction between the two particles.
30 
31  See \ref graphs "Graphs in IMP" for more information.
32  */
33 IMP_GRAPH(InteractionGraph, undirected, Particle*, Pointer<Object>);
34 
35 
36 //! Gets all of the Subsets of a SubsetGraph
37 IMPDOMINOEXPORT Subsets get_subsets(const SubsetGraph &g);
38 
39 
40 /** Compute the exact
41  \external{http://en.wikipedia.org/wiki/Junction_tree,junction tree}
42  for an interaction graph. The resulting graph has the junction tree
43  properties
44  - it is a tree
45  - for any two vertices whose subsets both contain a vertex, that vertex
46  is contained in all subsets along the path connecting those two vertices.
47 
48  \note the junction tree is not nececessarily deterministic (you can
49  get different answers if you run it different times with the same inputs).
50 */
51 IMPDOMINOEXPORT SubsetGraph
53 
54 
55 #ifndef IMP_DOMINO
56 /** \name Debugging Junction Trees
57  @{ */
58 IMPDOMINOEXPORT InteractionGraph
59 get_triangulated(const InteractionGraph& input);
60 
61 
63 
64 IMPDOMINOEXPORT CliqueGraph get_clique_graph(const InteractionGraph& input);
65 
66 IMPDOMINOEXPORT SubsetGraph get_minimum_spanning_tree(const CliqueGraph& input);
67 
68 
69 /** @} */
70 #endif
71 
72 /** The restraint graph is formed by having one node per restraint
73  and an edge connecting two restraints if they share input
74  particles. The associated Subsets are the set of input particles
75  for the restraint, projected onto ps.
76 
77  \note The graph for the optimized restraints (after temporary
78  application of OptimizeContainers and OptimizeRestraints) is
79  returned.
80 */
81 IMPDOMINOEXPORT
82 SubsetGraph get_restraint_graph(ScoringFunctionAdaptor rs,
83  const ParticleStatesTable *pst);
84 
85 
86 
87 
88 
89 /** Compute the interaction graph of the restraints and the specified
90  particles. The dependency graph in the model is traversed to
91  determine how the passed particles relate to the actual particles
92  read as input by the model. For example, if particles contains a
93  rigid body, then an restraint which uses a member of the rigid
94  body will have an edge from the rigid body particle.
95 
96  \note You may want to create an OptimizeRestraints object before
97  calling this function.
98 
99  \note These functions are here to aid in debugging of optimization
100  protocols that use Domino2. As a result, its signature and
101  functionality may change without notice.
102  @{
103  */
104 IMPDOMINOEXPORT InteractionGraph
105 get_interaction_graph( ScoringFunctionAdaptor rs,
106  const ParticleStatesTable *pst);
107 
108 IMPDOMINOEXPORT InteractionGraph
109 get_interaction_graph(ScoringFunctionAdaptor rs,
110  const ParticlesTemp &pst);
111 
112 /** Assuming that all the particles have Cartesian coordinates,
113  output edges corresponding to the edges in the interaction graph.
114  The edges are named by the restraint which induces them.
115 */
116 IMPDOMINOEXPORT display::Geometries
118 
119 
120 /** Display the subsets of a subset graph, superimposed on the 3D
121  coordinates of the particles.
122 */
123 IMPDOMINOEXPORT display::Geometries
125 
126 
127 /** A directed graph on subsets of vertices. Each vertex is
128  named with an Subset.
129  */
130 IMP_GRAPH(MergeTree, bidirectional, Subset, int);
131 
132 /** \see get_merge_tree(const SubsetGraph&)
133 
134  Compute the merge tree for a given restraint set and
135  particle states table. An OptimizeRestraints object is
136  created to improve the InteractionGraph used internally.
137  */
138 IMPDOMINOEXPORT
139 MergeTree get_merge_tree(ScoringFunctionAdaptor input,
140  const ParticleStatesTable *pst);
141 
142 /** \see get_merge_tree(RestraintSet*,const ParticleStatesTable*)
143 
144  Compute the merge tree from a junction tree.
145 
146  \note the merge tree is not nececessarily deterministic (you can
147  get different answers if you run it different times with the same inputs).
148  */
149 IMPDOMINOEXPORT
150 MergeTree get_merge_tree(const SubsetGraph &junction_tree);
151 
152 
153 
154 /** \see get_merge_tree(RestraintSet*,const ParticleStatesTable*)
155 
156  Compute the merge tree from a junction tree, attempting to keep it fairly
157  balanced.
158 
159  \note the merge tree is not nececessarily deterministic (you can
160  get different answers if you run it different times with the same inputs).
161  */
162 IMPDOMINOEXPORT
163 MergeTree get_balanced_merge_tree(const SubsetGraph &junction_tree);
164 
165 
166 IMPDOMINOEXPORT
167 bool get_is_merge_tree(const MergeTree &tree, Subset all, bool verbose=true);
168 
169 
170 /** \name Read and write merge trees
171  Merge trees can be written to an read from a text stream. As always,
172  this requires a canonical particles list whose order is the same
173  for the reading and writing.
174  @{
175 */
176 
177 IMPDOMINOEXPORT
178 void write_merge_tree(const MergeTree &tree, const ParticlesTemp &ps,
179  std::ostream &out);
180 IMPDOMINOEXPORT
181 MergeTree read_merge_tree(std::istream &input,
182  const ParticlesTemp &ps);
183 /** @} */
184 
185 IMPDOMINO_END_NAMESPACE
186 
187 #endif /* IMPDOMINO_SUBSET_GRAPHS_H */