doc/graphs.dox
author marci
Thu, 16 Sep 2004 14:27:27 +0000
changeset 869 c19cf2007a7a
parent 756 c54cf1e83039
child 873 f3a30fda2e49
permissions -rw-r--r--
more docs
     1 /*!
     2 
     3 \page graphs How to use graphs
     4 
     5 The primary data structures of HugoLib 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 in incoming and outgoing edges of a given node. 
     9 
    10 
    11 Each graph should meet the \ref ConstGraph concept. This concept does
    12 makes it possible to change the graph (i.e. it is not possible to add
    13 or delete edges or nodes). Most of the graph algorithms will run on
    14 these graphs.
    15 
    16 The graphs meeting the \ref ExtendableGraph concept allow node and
    17 edge addition. You can also "clear" (i.e. erase all edges and nodes)
    18 such a graph.
    19 
    20 In case of graphs meeting the full feature \ref ErasableGraph concept
    21 you can also erase individual edges and node in arbitrary order.
    22 
    23 The implemented graph structures are the following.
    24 \li \ref hugo::ListGraph "ListGraph" is the most versatile graph class. It meets
    25 the ErasableGraph concept and it also have some convenience features.
    26 \li \ref hugo::SmartGraph "SmartGraph" is a more memory
    27 efficient version of \ref hugo::ListGraph "ListGraph". The
    28 price of it is that it only meets the \ref ExtendableGraph concept,
    29 so 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".
    33 The difference is that whenever you add a
    34 new edge to the graph, it actually adds a pair of oppositely directed edges.
    35 They are linked together so it is possible to access the counterpart of an
    36 edge. An even more important feature is that using these classes you can also
    37 attach data to the edges in such a way that the stored data
    38 are shared by the edge pairs. 
    39 \li \ref hugo::FullGraph "FullGraph"
    40 implements a full graph. It is a \ref ConstGraph, so you cannot
    41 change the number of nodes once it is constructed. It is extremely memory
    42 efficient: it uses constant amount of memory independently from the number of
    43 the 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
    47 can 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
    49 the edge set of another graph. The base graph can be an arbitrary graph and it
    50 is 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 
    57 The graph structures itself can not store data attached
    58 to the edges and nodes. However they all provide
    59 \ref maps "map classes"
    60 to dynamically attach data the to graph components.
    61 
    62 
    63 
    64 
    65 The following program demonstrates the basic features of HugoLib's graph
    66 structures.
    67 
    68 \code
    69 #include <iostream>
    70 #include <hugo/list_graph.h>
    71 
    72 using namespace hugo;
    73 
    74 int main()
    75 {
    76   typedef ListGraph Graph;
    77 \endcode
    78 
    79 ListGraph is one of HugoLib's graph classes. It is based on linked lists,
    80 therefore 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++)
    93     g.addNode();
    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 
   100 After some convenience typedefs we create a graph and add three nodes to it.
   101 Then 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 
   110 Here we iterate through all nodes of the graph. We use a constructor of the
   111 node iterator to initialize it to the first node. The next member function is
   112 used to step to the next node, and valid is used to check if we have passed the
   113 last 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 
   123 Here you can see an alternative way to iterate through all nodes. Here we use a
   124 member function of the graph to initialize the node iterator to the first node
   125 of the graph. Using next on the iterator pointing to the last node invalidates
   126 the iterator i.e. sets its value to INVALID. Checking for this value is
   127 equivalent to using the valid member function.
   128 
   129 Both of the previous code fragments print out the same:
   130 
   131 \code
   132 Nodes: 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
   143 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
   144 \endcode
   145 
   146 We can also iterate through all edges of the graph very similarly. The head and
   147 tail 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
   164 Out-edges of node 2: (2,0) (2,1)
   165 In-edges of node 2: (0,2) (1,2)
   166 \endcode
   167 
   168 We can also iterate through the in and out-edges of a node. In the above
   169 example 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
   184 Id Edge  Value
   185 4  (0,2) 6
   186 2  (1,2) 8
   187 5  (0,1) 5
   188 0  (2,1) 10
   189 3  (1,0) 7
   190 1  (2,0) 9
   191 \endcode
   192 
   193 In generic graph optimization programming graphs are not containers rather
   194 incidence structures which are iterable in many ways. HugoLib introduces
   195 concepts that allow us to attach containers to graphs. These containers are
   196 called maps.
   197 
   198 In the example above we create an EdgeMap which assigns an int value to all
   199 edges of the graph. We use the set member function of the map to write values
   200 into the map and the operator[] to retrieve them.
   201 
   202 Here we used the maps provided by the ListGraph class, but you can also write
   203 your own maps. You can read more about using maps \ref maps "here".
   204 
   205 */