Changeset 6:da96f28684f7 in lemon-tutorial

Timestamp:

10/23/08 14:07:30 (16 years ago)

Author:

Peter Kovacs <kpeter@…>

Branch:

default

Phase:

public

Message:

Extend and improve the first two chapters

Files:

• getting_started.dox (modified) (7 diffs)
• intro.dox (modified) (1 diff)

getting_started.dox

@@ -18 +18 @@
 
 /**
-\page getting_started How to Start Using LEMON
+\page getting_started Getting Started
 
 In this page we detail how to start using LEMON, from downloading it to
@@ -25 +25 @@
 have a basic knowledge of your operating system and C++ programming
 language. The procedure is pretty straightforward, but if you have any
-difficulties don't hesitate to
+difficulties do not hesitate to
 <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
 
@@ -32 +32 @@
 In LEMON we use C++ templates heavily, thus compilation takes a
 considerable amount of time and memory. So some decent box would be
-advantageous. But otherwise there are no special hardware requirements.
+advantageousm, but otherwise there are no special hardware requirements.
 
 You will need a recent C++ compiler. Our primary target is the GNU C++
 Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
-Compiler (icc) and Microsoft Visual C++ .NET 2003, 2005.
-If you want to develop with LEMON under Windows you could consider
-using Cygwin.
+Compiler (icc) and Microsoft Visual C++ (on Windows).
+If you want to develop with LEMON under Windows, you can use a Windows
+installer or you can consider using Cygwin.
 
 In this description we will suppose a Linux environment and GNU C++ Compiler.
+If you would like to develop under Windows and use a Windows installer,
+you could skip the following sections and continue reading \ref hello_lemon.
+However keep in mind that you have to make appropriate steps instead of
+the instructions detailed here to be able to compile the example code
+with your compiler.
 
 \subsection requirements_lp LP Solver Requirements
 
 The LEMON LP solver interface can use the GLPK (GNU Linear Programming
-Kit), CPLEX (was tested with CPLEX 7.5) and SoPlex solver. If you want
-to use it you will need at least one of these. See \ref configure_flags
-how to enable these at compile time.
+Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
+least one of these.
+See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.
 
 \section download_lemon How to Download LEMON
 
-You can download LEMON from the LEMON web site:
-<a href="http://lemon.cs.elte.hu/">https://lemon.cs.elte.hu/</a>.
-There you will find released versions in form of <tt>.tar.gz</tt> files.
+You can download LEMON from our web site:
+<a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.
+There you will find released versions in form of <tt>.tar.gz</tt> files
+(and Windows installers).
 If you want a developer version (for example you want to contribute in
-developing the library LEMON) then you might want to use our Mercurial
-repository. This case is detailed later, so from now on we suppose that
-you downloaded a <tt>.tar.gz</tt> file.
+developing LEMON) then you might want to use our Mercurial repository.
+This case is detailed \ref hg_checkout "later", so from now on we
+suppose that you downloaded a <tt>.tar.gz</tt> file.
 
 \section install_lemon How to Install LEMON
@@ -118 +124 @@
 \endverbatim
 This step is optional, but recommended. It runs the test programs that
-we developed for LEMON to check whether the library works properly on
+have been developed for LEMON to check whether the library works properly on
 your platform.
 
@@ -131 +137 @@
 
 Several other configure flags can be passed to <tt>./configure</tt>.
-For more information see <tt>./configure --help</tt> and the INSTALL
-file in the install directory.
+For more information see the <b><tt>INSTALL</tt></b> file.
 
 \section hg_checkout How to Checkout LEMON from our Mercurial Repository
 
-You can obtain the latest version of LEMON from our Mercurial repository.
-To do this issue the following command:
-\verbatim
-hg clone http://lemon.cs.elte.hu/hg/lemon lemon-src
+You can obtain the latest (developer) version of LEMON from our Mercurial
+repository. To do this issue the following command.
+\verbatim
+hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
 \endverbatim
 
@@ -145 +150 @@
 
 You can compile the code from the repository similarly to the packaged
-version, but you will need to run <b><tt>autoreconf -vif</tt></b> or
-<b><tt>./bootstrap</tt></b> in some older environment before
+version, but you will need to run <b><tt>autoreconf -vif</tt></b>
+(or <b><tt>./bootstrap</tt></b> in some older environment) before
 <tt>./configure</tt>. See <tt>./configure --help</tt> for options.
 For bootstrapping you will need the following tools:
@@ -158 +163 @@
 You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.
 
+\section hello_lemon Compile Your First Code
+
+If you have installed LEMON on your system you can paste the following
+code segment into a file called <tt>hello_lemon.cc</tt> to have a first
+working program that uses LEMON.
+
+\dontinclude hello_lemon.cc
+\skip #include
+\until }
+
+First let us briefly explain how this example program works.
+(The used notions will be discussed in detail in the following chapter.)
+
+After some convenience typedefs we create a directed graph (\e digraph)
+and add some nodes and arcs to it.
+ListDigraph is one of the digraph classes implemented in LEMON.
+It is based on linked lists, therefore iterating through its nodes and
+arcs is fast.
+
+Then we iterate through all nodes of the digraph and print their unique
+IDs. We use a constructor of the node iterator to initialize it to the
+first node.
+The <tt>operator++</tt> is used to step to the next node. After the last
+node the iterator becomes invalid (i.e. it is set to \c INVALID).
+This is what we exploit in the stop condition.
+We iterate through all arcs of the digraph very similarly and print the
+IDs of their source (tail) and target (head) nodes using the \c source()
+and \c target() member functions.
+
+After that we create an arc map, which is actually a mapping that assigns
+an \c int value (length) to each arc, and we set this value for each arc.
+Finally we iterate through all arcs again and print their lengths.
+
+Now let's compile this simple example program.
+
+\subsection hello_lemon_system If LEMON is Installed System-Wide
+
+If your installation of LEMON into directory \c /usr/local was
+successful, then it is very easy to compile this program with the
+following command (the argument <tt>-lemon</tt> tells the compiler
+that we are using the installed LEMON):
+
+\verbatim
+g++ hello_lemon.cc -o hello_lemon -lemon
+\endverbatim
+
+As a result you will get the exacutable \c hello_lemon in the current
+directory, which you can run by the following command.
+
+\verbatim
+./hello_lemon
+\endverbatim
+
+\subsection hello_lemon_user If LEMON is Installed User-Local
+
+Compiling the code is a bit more difficult if you installed LEMON
+user-local into a directory (e.g. <tt>~/lemon</tt>) or if you just
+skipped the step <tt>make install</tt>.
+You have to issue a command like this.
+
+\verbatim
+g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs
+\endverbatim
+
+\subsubsection hello_lemon_pkg_config Use pkg-config
+
+\todo Write this sub-subsection (\ref hello_lemon_pkg_config).
+
+If everything has gone well, then our program prints out the followings.
+
+\verbatim
+Hello World!
+This is LEMON library here. We have a direceted graph.
+
+Nodes: 3 2 1 0
+Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)
+
+There is a map on the arcs (length):
+
+length(2,3)=10
+length(1,3)=25
+length(1,2)=5
+length(0,2)=20
+length(0,1)=10
+\endverbatim
+
+You may note that iterating through the nodes and arcs is done in the
+reverse order compared to the creating order (the IDs are in decreasing
+order).
+This is due to implementation aspects, that may differ at other graph
+types, moreover it may be changed in the next releases.
+Thus you should not exploit this method in any way, you should not
+suppose anything about the iteration order.
+
+If you managed to compile and run this example code without any problems,
+you can go on reading this tutorial to get to know more features and tools
+of LEMON.
+Otherwise if you encountered problems that you did not manage to solve,
+do not hesitate to
+<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>.
+
 */

intro.dox

@@ -22 +22 @@
 \section intro_lemon What is LEMON
 
-LEMON stands for <b>L</b>ibrary of <b>E</b>fficient <b>M</b>odels and
+<b>LEMON</b> stands for <b>L</b>ibrary of <b>E</b>fficient <b>M</b>odels and
 <b>O</b>ptimization in <b>N</b>etworks. It is a C++ template
-library aimed at combinatorial optimization tasks which often involve
-in working with graphs.
+library aimed at combinatorial optimization tasks, especially those
+working with graphs and networks.
 
 <b>LEMON is an <a class="el" href="http://opensource.org/">open&nbsp;source</a>
 project.
 You are free to use it in your commercial or non-commercial applications
-under very permissive \ref license "license terms".
-</b>
+under very permissive \ref license "license terms".</b>
+
+This library helps to write programs that solve optimization problems
+that arise frequently when designing and testing certain networks,
+for example in telecommunication, computer networks, logistics, scheduling,
+and other areas.
+A very natural way of modelling these networks is by means of a graph.
+Generally if you want to write any program that works with graphs,
+then you might find it useful and convenient to use LEMON.
+
+For more information visit the LEMON web site:
+<a href="http://lemon.cs.elte.hu/"><b>http://lemon.cs.elte.hu/</b></a>.
 
 \section intro_tutorial LEMON Tutorial
 
 This tutorial introduces the reader to the basic concepts and features of
-LEMON, and there are some sections about advanced topics showing the power
-of the various tools implemented in the library.
+LEMON, and there are also some sections about advanced topics showing the
+power of various tools implemented in the library.
 
-After getting familiar with the basic concepts you may start using LEMON
-with the help of the detailed documentation (that can also be used as a
-reference manual).
+After getting familiar with the basics of the library, you may start using
+LEMON with the help of the detailed documentation (that can also be used
+as a reference manual).
 
 */