doc/graphs.dox
author kpeter
Tue, 05 Feb 2008 11:24:32 +0000
changeset 2563 5841132a89fd
parent 2476 059dcdda37c5
permissions -rw-r--r--
Small fixes in README.
     1 /* -*- C++ -*-
     2  *
     3  * This file is a part of LEMON, a generic C++ optimization library
     4  *
     5  * Copyright (C) 2003-2008
     6  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
     7  * (Egervary Research Group on Combinatorial Optimization, EGRES).
     8  *
     9  * Permission to use, modify and distribute this software is granted
    10  * provided that this copyright notice appears in all copies. For
    11  * precise terms see the accompanying LICENSE file.
    12  *
    13  * This software is provided "AS IS" with no warranty of any kind,
    14  * express or implied, and with no claim as to its suitability for any
    15  * purpose.
    16  *
    17  */
    18 
    19 namespace lemon {
    20 
    21 /*!
    22 \page graphs Graphs
    23 
    24 \todo Write a new Graphs page. I think it should be contain the Graph,
    25 UGraph and BpUGraph concept. It should be describe the iterators and
    26 the basic functions and the differences of the implementations.
    27 
    28 The primary data structures of LEMON are the graph classes. They all
    29 provide a node list - edge list interface, i.e. they have
    30 functionalities to list the nodes and the edges of the graph as well
    31 as  incoming and outgoing edges of a given node. 
    32 
    33 Each graph should meet the \ref concepts::Graph "Graph" concept.
    34 This concept does not make it possible to change the graph (i.e. it is
    35 not possible to add or delete edges or nodes). Most of the graph
    36 algorithms will run on these graphs.
    37 
    38 
    39 In case of graphs meeting the full feature
    40 \ref concepts::ErasableGraph "ErasableGraph" concept
    41 you can also erase individual edges and nodes in arbitrary order.
    42 
    43 The implemented graph structures are the following.
    44 \li \ref ListGraph is the most versatile graph class. It meets
    45 the \ref concepts::ErasableGraph "ErasableGraph" concept
    46 and it also has some convenient extra features.
    47 \li \ref SmartGraph is a more memory efficient version of \ref ListGraph.
    48 The price of this is that it only meets the
    49 \ref concepts::ExtendableGraph "ExtendableGraph" concept,
    50 so you cannot delete individual edges or nodes.
    51 \li \ref FullGraph "FullGraph"
    52 implements a complete graph. It is a
    53 \ref concepts::Graph "Graph", so you cannot
    54 change the number of nodes once it is constructed. It is extremely memory
    55 efficient: it uses constant amount of memory independently from the number of
    56 the nodes of the graph. Of course, the size of the \ref maps-page "NodeMap"'s and
    57 \ref maps-page "EdgeMap"'s will depend on the number of nodes.
    58 
    59 \li \ref NodeSet "NodeSet" implements a graph with no edges. This class
    60 can be used as a base class of \ref lemon::EdgeSet "EdgeSet".
    61 \li \ref EdgeSet "EdgeSet" can be used to create a new graph on
    62 the node set of another graph. The base graph can be an arbitrary graph and it
    63 is possible to attach several \ref EdgeSet "EdgeSet"'s to a base graph.
    64 
    65 \todo Don't we need SmartNodeSet and SmartEdgeSet?
    66 \todo Some cross-refs are wrong.
    67 
    68 The graph structures themselves can not store data attached
    69 to the edges and nodes. However they all provide
    70 \ref maps-page "map classes"
    71 to dynamically attach data the to graph components.
    72 
    73 The following program demonstrates the basic features of LEMON's graph
    74 structures.
    75 
    76 \code
    77 #include <iostream>
    78 #include <lemon/list_graph.h>
    79 
    80 using namespace lemon;
    81 
    82 int main()
    83 {
    84   typedef ListGraph Graph;
    85 \endcode
    86 
    87 ListGraph is one of LEMON's graph classes. It is based on linked lists,
    88 therefore iterating throuh its edges and nodes is fast.
    89 
    90 \code
    91   typedef Graph::Edge Edge;
    92   typedef Graph::InEdgeIt InEdgeIt;
    93   typedef Graph::OutEdgeIt OutEdgeIt;
    94   typedef Graph::EdgeIt EdgeIt;
    95   typedef Graph::Node Node;
    96   typedef Graph::NodeIt NodeIt;
    97 
    98   Graph g;
    99   
   100   for (int i = 0; i < 3; i++)
   101     g.addNode();
   102   
   103   for (NodeIt i(g); i!=INVALID; ++i)
   104     for (NodeIt j(g); j!=INVALID; ++j)
   105       if (i != j) g.addEdge(i, j);
   106 \endcode
   107 
   108 After some convenient typedefs we create a graph and add three nodes to it.
   109 Then we add edges to it to form a complete graph.
   110 
   111 \code
   112   std::cout << "Nodes:";
   113   for (NodeIt i(g); i!=INVALID; ++i)
   114     std::cout << " " << g.id(i);
   115   std::cout << std::endl;
   116 \endcode
   117 
   118 Here we iterate through all nodes of the graph. We use a constructor of the
   119 node iterator to initialize it to the first node. The operator++ is used to
   120 step to the next node. Using operator++ on the iterator pointing to the last
   121 node invalidates the iterator i.e. sets its value to
   122 \ref INVALID. This is what we exploit in the stop condition.
   123 
   124 The previous code fragment prints out the following:
   125 
   126 \code
   127 Nodes: 2 1 0
   128 \endcode
   129 
   130 \code
   131   std::cout << "Edges:";
   132   for (EdgeIt i(g); i!=INVALID; ++i)
   133     std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")";
   134   std::cout << std::endl;
   135 \endcode
   136 
   137 \code
   138 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
   139 \endcode
   140 
   141 We can also iterate through all edges of the graph very similarly. The 
   142 \c target and
   143 \c source member functions can be used to access the endpoints of an edge.
   144 
   145 \code
   146   NodeIt first_node(g);
   147 
   148   std::cout << "Out-edges of node " << g.id(first_node) << ":";
   149   for (OutEdgeIt 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 
   153   std::cout << "In-edges of node " << g.id(first_node) << ":";
   154   for (InEdgeIt i(g, first_node); i!=INVALID; ++i)
   155     std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")"; 
   156   std::cout << std::endl;
   157 \endcode
   158 
   159 \code
   160 Out-edges of node 2: (2,0) (2,1)
   161 In-edges of node 2: (0,2) (1,2)
   162 \endcode
   163 
   164 We can also iterate through the in and out-edges of a node. In the above
   165 example we print out the in and out-edges of the first node of the graph.
   166 
   167 \code
   168   Graph::EdgeMap<int> m(g);
   169 
   170   for (EdgeIt e(g); e!=INVALID; ++e)
   171     m.set(e, 10 - g.id(e));
   172   
   173   std::cout << "Id Edge  Value" << std::endl;
   174   for (EdgeIt e(g); e!=INVALID; ++e)
   175     std::cout << g.id(e) << "  (" << g.id(g.source(e)) << "," << g.id(g.target(e))
   176       << ") " << m[e] << std::endl;
   177 \endcode
   178 
   179 \code
   180 Id Edge  Value
   181 4  (0,2) 6
   182 2  (1,2) 8
   183 5  (0,1) 5
   184 0  (2,1) 10
   185 3  (1,0) 7
   186 1  (2,0) 9
   187 \endcode
   188 
   189 As we mentioned above, graphs are not containers rather
   190 incidence structures which are iterable in many ways. LEMON introduces
   191 concepts that allow us to attach containers to graphs. These containers are
   192 called maps.
   193 
   194 In the example above we create an EdgeMap which assigns an integer value to all
   195 edges of the graph. We use the set member function of the map to write values
   196 into the map and the operator[] to retrieve them.
   197 
   198 Here we used the maps provided by the ListGraph class, but you can also write
   199 your own maps. You can read more about using maps \ref maps-page "here".
   200 
   201 */
   202 
   203 }
   204