doc/graphs.dox
author ladanyi
Fri, 20 May 2005 12:44:28 +0000
changeset 1433 e0ec5ce0771e
parent 1168 66400041ef2a
child 1631 e15162d8eca1
permissions -rw-r--r--
added a configuration header to the lemon directory
     1 /*!
     2 
     3 \page graphs How to use graphs
     4 
     5 The primary data structures of LEMON are the graph classes. They all
     6 provide a node list - edge list interface, i.e. they have
     7 functionalities to list the nodes and the edges of the graph as well
     8 as  incoming and outgoing edges of a given node. 
     9 
    10 
    11 Each graph should meet the
    12 \ref lemon::concept::StaticGraph "StaticGraph" concept.
    13 This concept does not
    14 make it possible to change the graph (i.e. it is not possible to add
    15 or delete edges or nodes). Most of the graph algorithms will run on
    16 these graphs.
    17 
    18 The graphs meeting the
    19 \ref lemon::concept::ExtendableGraph "ExtendableGraph"
    20 concept allow node and
    21 edge addition. You can also "clear" such a graph (i.e. erase all edges and nodes ).
    22 
    23 In case of graphs meeting the full feature
    24 \ref lemon::concept::ErasableGraph "ErasableGraph"
    25 concept
    26 you can also erase individual edges and nodes in arbitrary order.
    27 
    28 The implemented graph structures are the following.
    29 \li \ref lemon::ListGraph "ListGraph" is the most versatile graph class. It meets
    30 the \ref lemon::concept::ErasableGraph "ErasableGraph" concept
    31 and it also has some convenient extra features.
    32 \li \ref lemon::SmartGraph "SmartGraph" is a more memory
    33 efficient version of \ref lemon::ListGraph "ListGraph". The
    34 price of this is that it only meets the
    35 \ref lemon::concept::ExtendableGraph "ExtendableGraph" concept,
    36 so 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".
    40 The difference is that whenever you add a
    41 new edge to the graph, it actually adds a pair of oppositely directed edges.
    42 They are linked together so it is possible to access the counterpart of an
    43 edge. An even more important feature is that using these classes you can also
    44 attach data to the edges in such a way that the stored data
    45 are shared by the edge pairs. 
    46 \li \ref lemon::FullGraph "FullGraph"
    47 implements a complete graph. It is a
    48 \ref lemon::concept::StaticGraph "StaticGraph", so you cannot
    49 change the number of nodes once it is constructed. It is extremely memory
    50 efficient: it uses constant amount of memory independently from the number of
    51 the 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
    55 can 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
    57 the node set of another graph. The base graph can be an arbitrary graph and it
    58 is 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 
    63 The graph structures themselves can not store data attached
    64 to the edges and nodes. However they all provide
    65 \ref maps-page "map classes"
    66 to dynamically attach data the to graph components.
    67 
    68 The following program demonstrates the basic features of LEMON's graph
    69 structures.
    70 
    71 \code
    72 #include <iostream>
    73 #include <lemon/list_graph.h>
    74 
    75 using namespace lemon;
    76 
    77 int main()
    78 {
    79   typedef ListGraph Graph;
    80 \endcode
    81 
    82 ListGraph is one of LEMON's graph classes. It is based on linked lists,
    83 therefore 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++)
    96     g.addNode();
    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 
   103 After some convenient typedefs we create a graph and add three nodes to it.
   104 Then 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 
   113 Here we iterate through all nodes of the graph. We use a constructor of the
   114 node iterator to initialize it to the first node. The operator++ is used to
   115 step to the next node. Using operator++ on the iterator pointing to the last
   116 node invalidates the iterator i.e. sets its value to
   117 \ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.
   118 
   119 The previous code fragment prints out the following:
   120 
   121 \code
   122 Nodes: 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
   133 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
   134 \endcode
   135 
   136 We 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
   155 Out-edges of node 2: (2,0) (2,1)
   156 In-edges of node 2: (0,2) (1,2)
   157 \endcode
   158 
   159 We can also iterate through the in and out-edges of a node. In the above
   160 example 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
   175 Id Edge  Value
   176 4  (0,2) 6
   177 2  (1,2) 8
   178 5  (0,1) 5
   179 0  (2,1) 10
   180 3  (1,0) 7
   181 1  (2,0) 9
   182 \endcode
   183 
   184 As we mentioned above, graphs are not containers rather
   185 incidence structures which are iterable in many ways. LEMON introduces
   186 concepts that allow us to attach containers to graphs. These containers are
   187 called maps.
   188 
   189 In the example above we create an EdgeMap which assigns an integer value to all
   190 edges of the graph. We use the set member function of the map to write values
   191 into the map and the operator[] to retrieve them.
   192 
   193 Here we used the maps provided by the ListGraph class, but you can also write
   194 your own maps. You can read more about using maps \ref maps-page "here".
   195 
   196 */