source:lemon-0.x/doc/graphs.dox@808:9cabbdd73375

Last change on this file since 808:9cabbdd73375 was 808:9cabbdd73375, checked in by Alpar Juttner, 15 years ago

Bug: This file must be updated.

File size: 6.7 KB
Line
1/*!
2
3\page graphs How to use graphs
4
5The primary data structures of HugoLib are the graph classes. They all
6provide a node list - edge list interface, i.e. they have
7functionalities to list the nodes and the edges of the graph as well
8as in incoming and outgoing edges of a given node.
9
10
11Each graph should meet the \ref ConstGraph concept. This concept does
12makes it possible to change the graph (i.e. it is not possible to add
13or delete edges or nodes). Most of the graph algorithms will run on
14these graphs.
15
16The graphs meeting the \ref ExtendableGraph concept allow node and
17edge addition. You can also "clear" (i.e. erase all edges and nodes)
18such a graph.
19
20In case of graphs meeting the full feature \ref ErasableGraph concept
21you can also erase individual edges and node in arbitrary order.
22
23The implemented graph structures are the following.
24\li \ref hugo::ListGraph "ListGraph" is the most versatile graph class. It meets
25the ErasableGraph concept and it also have some convenience features.
26\li \ref hugo::SmartGraph "SmartGraph" is a more memory
27efficient version of \ref hugo::ListGraph "ListGraph". The
28price of it is that it only meets the \ref ExtendableGraph concept,
29so you cannot delete individual edges or nodes.
30\li \ref hugo::SymListGraph "SymListGraph" and
31\ref hugo::SymSmartGraph "SymSmartGraph" classes are very similar to
32\ref hugo::ListGraph "ListGraph" and \ref hugo::SmartGraph "SmartGraph".
33The difference is that whenever you add a
34new edge to the graph, it actually adds a pair of oppositely directed edges.
35They are linked together so it is possible to access the counterpart of an
36edge. An even more important feature is that using these classes you can also
37attach data to the edges in such a way that the stored data
38are shared by the edge pairs.
39\li \ref hugo::FullGraph "FullGraph"
40implements a full graph. It is a \ref ConstGraph, so you cannot
41change the number of nodes once it is constructed. It is extremely memory
42efficient: it uses constant amount of memory independently from the number of
43the nodes of the graph. Of course, the size of the \ref maps "NodeMap"'s and
44\ref maps "EdgeMap"'s will depend on the number of nodes.
45
46\li \ref hugo::NodeSet "NodeSet" implements a graph with no edges. This class
47can be used as a base class of \ref hugo::EdgeSet "EdgeSet".
48\li \ref hugo::EdgeSet "EdgeSet" can be used to create a new graph on
49the edge set of another graph. The base graph can be an arbitrary graph and it
50is possible to attach several \ref hugo::EdgeSet "EdgeSet"'s to a base graph.
51
52\todo Don't we need SmartNodeSet and SmartEdgeSet?
53\todo Some cross-refs are wrong.
54
55\bug This file must be updated accordig to the new stile iterators.
56
57The graph structures itself can not store data attached
58to the edges and nodes. However they all provide
59\ref maps "map classes"
60to dynamically attach data the to graph components.
61
62
63
64
65The following program demonstrates the basic features of HugoLib's graph
66structures.
67
68\code
69#include <iostream>
70#include <hugo/list_graph.h>
71
72using namespace hugo;
73
74int main()
75{
76  typedef ListGraph Graph;
77\endcode
78
79ListGraph is one of HugoLib's graph classes. It is based on linked lists,
80therefore iterating throuh its edges and nodes is fast.
81
82\code
83  typedef Graph::Edge Edge;
84  typedef Graph::InEdgeIt InEdgeIt;
85  typedef Graph::OutEdgeIt OutEdgeIt;
86  typedef Graph::EdgeIt EdgeIt;
87  typedef Graph::Node Node;
88  typedef Graph::NodeIt NodeIt;
89
90  Graph g;
91
92  for (int i = 0; i < 3; i++)
94
95  for (NodeIt i(g); g.valid(i); g.next(i))
96    for (NodeIt j(g); g.valid(j); g.next(j))
97      if (i != j) g.addEdge(i, j);
98\endcode
99
100After some convenience typedefs we create a graph and add three nodes to it.
101Then we add edges to it to form a full graph.
102
103\code
104  std::cout << "Nodes:";
105  for (NodeIt i(g); g.valid(i); g.next(i))
106    std::cout << " " << g.id(i);
107  std::cout << std::endl;
108\endcode
109
110Here we iterate through all nodes of the graph. We use a constructor of the
111node iterator to initialize it to the first node. The next member function is
112used to step to the next node, and valid is used to check if we have passed the
113last one.
114
115\code
116  std::cout << "Nodes:";
117  NodeIt n;
118  for (g.first(n); n != INVALID; g.next(n))
119    std::cout << " " << g.id(n);
120  std::cout << std::endl;
121\endcode
122
123Here you can see an alternative way to iterate through all nodes. Here we use a
124member function of the graph to initialize the node iterator to the first node
125of the graph. Using next on the iterator pointing to the last node invalidates
126the iterator i.e. sets its value to INVALID. Checking for this value is
127equivalent to using the valid member function.
128
129Both of the previous code fragments print out the same:
130
131\code
132Nodes: 2 1 0
133\endcode
134
135\code
136  std::cout << "Edges:";
137  for (EdgeIt i(g); g.valid(i); g.next(i))
138    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")";
139  std::cout << std::endl;
140\endcode
141
142\code
143Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
144\endcode
145
146We can also iterate through all edges of the graph very similarly. The head and
147tail member functions can be used to access the endpoints of an edge.
148
149\code
150  NodeIt first_node(g);
151
152  std::cout << "Out-edges of node " << g.id(first_node) << ":";
153  for (OutEdgeIt i(g, first_node); g.valid(i); g.next(i))
154    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")";
155  std::cout << std::endl;
156
157  std::cout << "In-edges of node " << g.id(first_node) << ":";
158  for (InEdgeIt i(g, first_node); g.valid(i); g.next(i))
159    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")";
160  std::cout << std::endl;
161\endcode
162
163\code
164Out-edges of node 2: (2,0) (2,1)
165In-edges of node 2: (0,2) (1,2)
166\endcode
167
168We can also iterate through the in and out-edges of a node. In the above
169example we print out the in and out-edges of the first node of the graph.
170
171\code
172  Graph::EdgeMap<int> m(g);
173
174  for (EdgeIt e(g); g.valid(e); g.next(e))
175    m.set(e, 10 - g.id(e));
176
177  std::cout << "Id Edge  Value" << std::endl;
178  for (EdgeIt e(g); g.valid(e); g.next(e))
179    std::cout << g.id(e) << "  (" << g.id(g.tail(e)) << "," << g.id(g.head(e))
180      << ") " << m[e] << std::endl;
181\endcode
182
183\code
184Id Edge  Value
1854  (0,2) 6
1862  (1,2) 8
1875  (0,1) 5
1880  (2,1) 10
1893  (1,0) 7
1901  (2,0) 9
191\endcode
192
193In generic graph optimization programming graphs are not containers rather
194incidence structures which are iterable in many ways. HugoLib introduces
195concepts that allow us to attach containers to graphs. These containers are
196called maps.
197
198In the example above we create an EdgeMap which assigns an int value to all
199edges of the graph. We use the set member function of the map to write values
200into the map and the operator[] to retrieve them.
201
202Here we used the maps provided by the ListGraph class, but you can also write
203your own maps. You can read more about using maps \ref maps "here".
204
205*/
Note: See TracBrowser for help on using the repository browser.