COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/graphs.dox @ 1168:66400041ef2a

Last change on this file since 1168:66400041ef2a was 1168:66400041ef2a, checked in by athos, 18 years ago

Corrected spelling errors.

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