# source:lemon-0.x/doc/graphs.dox@1591:03aa0a6c8dca

Last change on this file since 1591:03aa0a6c8dca was 1200:ae69f556b429, checked in by Alpar Juttner, 16 years ago

Doc improvements

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