[Lemon-commits] [lemon_svn] alpar: r2921 - hugo/trunk/doc
Lemon SVN
svn at lemon.cs.elte.hu
Mon Nov 6 21:51:15 CET 2006
Author: alpar
Date: Mon Sep 4 22:07:37 2006
New Revision: 2921
Added:
hugo/trunk/doc/algorithms.dox
hugo/trunk/doc/maps1.dox
hugo/trunk/doc/maps2.dox
Modified:
hugo/trunk/doc/Makefile.am
Log:
Add missing Tutorial dox files
Modified: hugo/trunk/doc/Makefile.am
==============================================================================
--- hugo/trunk/doc/Makefile.am (original)
+++ hugo/trunk/doc/Makefile.am Mon Sep 4 22:07:37 2006
@@ -7,6 +7,7 @@
doc/icons/geom/ftv2doc.png \
doc/icons/geom/ftv2folderclosed.png \
doc/icons/geom/ftv2folderopen.png \
+ doc/algorithms.dox \
doc/coding_style.dox \
doc/developers_interface.dox \
doc/dirs.dox \
@@ -18,6 +19,8 @@
doc/license.dox \
doc/mainpage.dox \
doc/maps.dox \
+ doc/maps1.dox \
+ doc/maps2.dox \
doc/named-param.dox \
doc/namespaces.dox \
doc/quicktour.dox \
Added: hugo/trunk/doc/algorithms.dox
==============================================================================
--- (empty file)
+++ hugo/trunk/doc/algorithms.dox Mon Sep 4 22:07:37 2006
@@ -0,0 +1,5 @@
+/**
+\page algorithms Algorithms
+
+Place-holder page for algorithms.
+*/
Added: hugo/trunk/doc/maps1.dox
==============================================================================
--- (empty file)
+++ hugo/trunk/doc/maps1.dox Mon Sep 4 22:07:37 2006
@@ -0,0 +1,72 @@
+/**
+\page maps1 Maps I.
+
+In the previous section we discussed graph topology. That is the skeleton a complex
+graph represented data-set needs. But how to assign the data itself to that skeleton?<br>
+Here come the \b maps in.
+
+\section maps_intro Introduction to maps
+Maps play a central role in LEMON. As their name suggests, they map a certain range of <i>keys</i> to certain <i>values</i>.
+In LEMON there is many types of maps. Each map has two typedef's to determine the types of keys and values, like this:
+\code
+ typedef Edge Key;
+ typedef double Value;
+\endcode
+(Except matrix maps, they have two key types.)
+
+To make easy to use them - especially as template parameters - there are <i>map concepts</i> like by graph classes.
+<ul>
+<li>\ref ReadMap - values can be red out with the \c operator[].
+\code value_typed_variable = map_instance[key_value]; \endcode
+</li>
+<li>\ref WriteMap - values can be set with the \c set() member function.
+\code map_instance.set(key_value, value_typed_expression); \endcode
+</li>
+<li>\ref ReadWriteMap - it's just a shortcut to indicate that the map is both
+readable and writable. It is delivered from them.
+</li>
+<li>\ref ReferenceMap - a subclass of ReadWriteMap. It has two additional typedefs
+<i>Reference</i> and <i>ConstReference</i> and two overloads of \c operator[] to
+providing you constant or non-constant reference to the value belonging to a key,
+so you have a direct access to the memory address where it is stored.
+</li>
+<li>And there are the Matrix version of these maps, where the values are assigned to a pair of keys.
+The keys can be different types. (\ref ReadMatrixMap, \ref WriteMatrixMap, \ref ReadWriteMatrixMap, \ref ReferenceMatrixMap)
+</li>
+</ul>
+
+\section maps_graph Graphs' maps
+Every \ref MappableGraphComponent "mappable" graph class has two public templates: NodeMap<VALUE> and EdgeMap<VALUE>
+satisfying the \ref GraphMap concept.
+If you want to assign data to nodes, just declare a NodeMap with the corresponding
+type. As an example, think of a edge-weighted directed graph.
+\code ListGraph::EdgeMap<int> weight(graph); \endcode
+You can see that the map needs the graph hows edges will mapped, but nothing more.
+
+If the graph class is extendable or erasable the map will automatically follow
+the changes you make. If a new node is added a default value is mapped to it.
+You can define the default value by passing a second argument to the map's constructor.
+\code ListGraph::EdgeMap<int> weight(graph, 13); \endcode
+But keep in mind that \c VALUE has to have copy constructor.
+
+Of course \c VALUE can be a rather complex type.
+
+For practice let's see the following template function (from \ref maps_summary "maps-summary.cc" in the \ref demo directory)!
+\dontinclude maps_summary.cc
+\skip template
+\until }
+The task is simple. We need the summary of some kind of data assigned to a graph's nodes.
+(Whit a little trick the summary can be calculated only to a sub-graph without changing
+this code. See \ref SubGraph techniques - that's LEMON's true potential.)
+
+And the usage is simpler than the declaration suggests. The compiler deduces the
+template specialization, so the usage is like a simple function call.
+\skip std
+\until ;
+
+Most of the time you will probably use graph maps, but keep in mind, that in LEMON maps are more general and can be used widely.
+
+If you want some 'real-life' examples see the next page, where we discuss \ref algorithms
+(coming soon) and will use maps hardly.
+Or if you want to know more about maps read these \ref maps2 "advanced map techniques".
+*/
Added: hugo/trunk/doc/maps2.dox
==============================================================================
--- (empty file)
+++ hugo/trunk/doc/maps2.dox Mon Sep 4 22:07:37 2006
@@ -0,0 +1,72 @@
+/**
+\page maps2 Maps II.
+
+Here we discuss some advanced map techniques. Like writing your own maps or how to
+extend/modify a maps functionality with adaptors.
+
+\section custom_maps Writing Custom ReadMap
+\subsection custom_read_maps Readable Maps
+
+Readable maps are very frequently used as the input of an
+algorithm. For this purpose the most straightforward way is the use of the
+default maps provided by LEMON's graph structures.
+Very often however, it is more
+convenient and/or more efficient to write your own readable map.
+
+You can find some examples below. In these examples \c Graph is the
+type of the particular graph structure you use.
+
+
+This simple map assigns \f$\pi\f$ to each edge.
+
+\code
+struct MyMap
+{
+ typedef double Value;
+ typedef Graph::Edge Key;
+ double operator[](Key e) const { return M_PI;}
+};
+\endcode
+
+An alternative way to define maps is to use MapBase
+
+\code
+struct MyMap : public MapBase<Graph::Edge,double>
+{
+ Value operator[](Key e) const { return M_PI;}
+};
+\endcode
+
+Here is a bit more complex example.
+It provides a length function obtained
+from a base length function shifted by a potential difference.
+
+\code
+class ReducedLengthMap : public MapBase<Graph::Edge,double>
+{
+ const Graph &g;
+ const Graph::EdgeMap<double> &orig_len;
+ const Graph::NodeMap<double> &pot;
+
+public:
+ Value operator[](Key e) const {
+ return orig_len[e]-(pot[g.target(e)]-pot[g.source(e)]);
+ }
+
+ ReducedLengthMap(const Graph &_g,
+ const Graph::EdgeMap &_o,
+ const Graph::NodeMap &_p)
+ : g(_g), orig_len(_o), pot(_p) {};
+};
+\endcode
+
+Then, you can call e.g. Dijkstra algoritm on this map like this:
+\code
+ ...
+ ReducedLengthMap rm(g,len,pot);
+ Dijkstra<Graph,ReducedLengthMap> dij(g,rm);
+ dij.run(s);
+ ...
+\endcode
+
+*/
More information about the Lemon-commits
mailing list