# HG changeset patch # User Peter Kovacs # Date 1224763650 -7200 # Node ID da96f28684f7ecb0a928a2486209a2eecd857e40 # Parent 29baa4a189bffe0b76d94fca01b80b08e3d64a8e Extend and improve the first two chapters diff -r 29baa4a189bf -r da96f28684f7 getting_started.dox --- a/getting_started.dox Thu Oct 23 14:06:53 2008 +0200 +++ b/getting_started.dox Thu Oct 23 14:07:30 2008 +0200 @@ -17,46 +17,52 @@ */ /** -\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 your computer, through the steps of installation, to showing a simple "Hello World" type program that already uses LEMON. We assume that you 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 ask. \section requirements_lemon Hardware and Software Requirements 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 INSTALL file how to enable these at compile time. \section download_lemon How to Download LEMON -You can download LEMON from the LEMON web site: -https://lemon.cs.elte.hu/. -There you will find released versions in form of .tar.gz files. +You can download LEMON from our web site: +http://lemon.cs.elte.hu/. +There you will find released versions in form of .tar.gz 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 .tar.gz 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 .tar.gz file. \section install_lemon How to Install LEMON @@ -117,7 +123,7 @@ make check \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. \verbatim @@ -130,22 +136,21 @@ non-default location. Several other configure flags can be passed to ./configure. -For more information see ./configure --help and the INSTALL -file in the install directory. +For more information see the INSTALL 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: +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 lemon-src +hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src \endverbatim \section hg_compile How to Compile the Source from the Repository You can compile the code from the repository similarly to the packaged -version, but you will need to run autoreconf -vif or -./bootstrap in some older environment before +version, but you will need to run autoreconf -vif +(or ./bootstrap in some older environment) before ./configure. See ./configure --help for options. For bootstrapping you will need the following tools: @@ -157,4 +162,105 @@ To generate the documentation, run make html. You will need Doxygen 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 hello_lemon.cc 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 operator++ 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 -lemon 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. ~/lemon) or if you just +skipped the step make install. +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 +contact us. + */ diff -r 29baa4a189bf -r da96f28684f7 intro.dox --- a/intro.dox Thu Oct 23 14:06:53 2008 +0200 +++ b/intro.dox Thu Oct 23 14:07:30 2008 +0200 @@ -21,25 +21,35 @@ \section intro_lemon What is LEMON -LEMON stands for Library of Efficient Models and +LEMON stands for Library of Efficient Models and Optimization in Networks. 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. LEMON is an open source project. You are free to use it in your commercial or non-commercial applications -under very permissive \ref license "license terms". - +under very permissive \ref license "license terms". + +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: +http://lemon.cs.elte.hu/. \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). */