[Lemon-commits] [lemon_svn] ladanyi: r877 - hugo/trunk/doc

[Lemon SVN]

Author: ladanyi
Date: Fri May 28 09:48:16 2004
New Revision: 877

Added:
   hugo/trunk/doc/graphs.dox
Modified:
   hugo/trunk/doc/Doxyfile
   hugo/trunk/doc/mainpage.dox

Log:
Added a short tutorial on using graphs.

Modified: hugo/trunk/doc/Doxyfile
==============================================================================
--- hugo/trunk/doc/Doxyfile	(original)
+++ hugo/trunk/doc/Doxyfile	Fri May 28 09:48:16 2004
@@ -392,6 +392,7 @@
 # with spaces.
 
 INPUT                  = mainpage.dox \
+			 graphs.dox \
                          maps.dox coding_style.dox \
                          groups.dox \
                          ../src/hugo \

Added: hugo/trunk/doc/graphs.dox
==============================================================================
--- (empty file)
+++ hugo/trunk/doc/graphs.dox	Fri May 28 09:48:16 2004
@@ -0,0 +1,145 @@
+/*!
+
+\page graphs How to use graphs
+
+The following program demonstrates the basic features of HugoLib's graph
+structures.
+
+\code
+#include <iostream>
+#include <hugo/list_graph.h>
+
+using namespace hugo;
+
+int main()
+{
+  typedef ListGraph Graph;
+\endcode
+
+ListGraph is one of HugoLib's graph classes. It is based on linked lists,
+therefore iterating throuh its edges and nodes is fast.
+
+\code
+  typedef Graph::Edge Edge;
+  typedef Graph::InEdgeIt InEdgeIt;
+  typedef Graph::OutEdgeIt OutEdgeIt;
+  typedef Graph::EdgeIt EdgeIt;
+  typedef Graph::Node Node;
+  typedef Graph::NodeIt NodeIt;
+
+  Graph g;
+  
+  for (int i = 0; i < 3; i++)
+    g.addNode();
+  
+  for (NodeIt i(g); g.valid(i); g.next(i))
+    for (NodeIt j(g); g.valid(j); g.next(j))
+      if (i != j) g.addEdge(i, j);
+\endcode
+
+After some convenience typedefs we create a graph and add three nodes to it.
+Then we add edges to it to form a full graph.
+
+\code
+  std::cout << "Nodes:";
+  for (NodeIt i(g); g.valid(i); g.next(i))
+    std::cout << " " << g.id(i);
+  std::cout << std::endl;
+\endcode
+
+Here we iterate through all nodes of the graph. We use a constructor of the
+node iterator to initialize it to the first node. The next member function is
+used to step to the next node, and valid is used to check if we have passed the
+last one.
+
+\code
+  std::cout << "Nodes:";
+  NodeIt n;
+  for (g.first(n); n != INVALID; g.next(n))
+    std::cout << " " << g.id(n);
+  std::cout << std::endl;
+\endcode
+
+Here you can see an alternative way to iterate through all nodes. Here we use a
+member function of the graph to initialize the node iterator to the first node
+of the graph. Using next on the iterator pointing to the last node invalidates
+the iterator i.e. sets its value to INVALID. Checking for this value is
+equivalent to using the valid member function.
+
+Both of the previous code fragments print out the same:
+
+\code
+Nodes: 2 1 0
+\endcode
+
+\code
+  std::cout << "Edges:";
+  for (EdgeIt i(g); g.valid(i); g.next(i))
+    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")";
+  std::cout << std::endl;
+\endcode
+
+\code
+Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
+\endcode
+
+We can also iterate through all edges of the graph very similarly. The head and
+tail member functions can be used to access the endpoints of an edge.
+
+\code
+  NodeIt first_node(g);
+
+  std::cout << "Out-edges of node " << g.id(first_node) << ":";
+  for (OutEdgeIt i(g, first_node); g.valid(i); g.next(i))
+    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")"; 
+  std::cout << std::endl;
+
+  std::cout << "In-edges of node " << g.id(first_node) << ":";
+  for (InEdgeIt i(g, first_node); g.valid(i); g.next(i))
+    std::cout << " (" << g.id(g.tail(i)) << "," << g.id(g.head(i)) << ")"; 
+  std::cout << std::endl;
+\endcode
+
+\code
+Out-edges of node 2: (2,0) (2,1)
+In-edges of node 2: (0,2) (1,2)
+\endcode
+
+We can also iterate through the in and out-edges of a node. In the above
+example we print out the in and out-edges of the first node of the graph.
+
+\code
+  Graph::EdgeMap<int> m(g);
+
+  for (EdgeIt e(g); g.valid(e); g.next(e))
+    m.set(e, 10 - g.id(e));
+  
+  std::cout << "Id Edge  Value" << std::endl;
+  for (EdgeIt e(g); g.valid(e); g.next(e))
+    std::cout << g.id(e) << "  (" << g.id(g.tail(e)) << "," << g.id(g.head(e))
+      << ") " << m[e] << std::endl;
+\endcode
+
+\code
+Id Edge  Value
+4  (0,2) 6
+2  (1,2) 8
+5  (0,1) 5
+0  (2,1) 10
+3  (1,0) 7
+1  (2,0) 9
+\endcode
+
+In generic graph optimization programming graphs are not containers rather
+incidence structures which are iterable in many ways. HugoLib introduces
+concepts that allow us to attach containers to graphs. These containers are
+called maps.
+
+In the example above we create an EdgeMap which assigns an int value to all
+edges of the graph. We use the set member function of the map to write values
+into the map and the operator[] to retrieve them.
+
+Here we used the maps provided by the ListGraph class, but you can also write
+your own maps. You can read more about using maps \ref maps "here".
+
+*/

Modified: hugo/trunk/doc/mainpage.dox
==============================================================================
--- hugo/trunk/doc/mainpage.dox	(original)
+++ hugo/trunk/doc/mainpage.dox	Fri May 28 09:48:16 2004
@@ -1,6 +1,23 @@
 /**
 \mainpage
 
-Please make a better mainpage (doc/mainpage.dox).
+\section intro Introduction
 
-*/
\ No newline at end of file
+\subsection whatis What is HugoLib
+
+HugoLib stands for Hungarian Graph Optimization Library. It is a C++ template
+library aimed at combinatorial optimization tasks which often involve working
+with graphs. As the name also suggests, its development was started by
+Hungarian people.
+
+\subsection howtoread How to read this document
+
+If you are new to HugoLib, you probably should start \ref graphs "here".
+You can also find this page along with other under Related Pages (left-hand
+side frame).
+
+If you are more interested in details about data structures and algorithms then
+you should browse the reference manual part of the documentation. The Modules
+section is a good starting point for this.
+
+*/