1.1 --- a/getting_started.dox Thu Oct 23 14:06:53 2008 +0200
1.2 +++ b/getting_started.dox Thu Oct 23 14:07:30 2008 +0200
1.3 @@ -17,46 +17,52 @@
1.4 */
1.5
1.6 /**
1.7 -\page getting_started How to Start Using LEMON
1.8 +\page getting_started Getting Started
1.9
1.10 In this page we detail how to start using LEMON, from downloading it to
1.11 your computer, through the steps of installation, to showing a simple
1.12 "Hello World" type program that already uses LEMON. We assume that you
1.13 have a basic knowledge of your operating system and C++ programming
1.14 language. The procedure is pretty straightforward, but if you have any
1.15 -difficulties don't hesitate to
1.16 +difficulties do not hesitate to
1.17 <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
1.18
1.19 \section requirements_lemon Hardware and Software Requirements
1.20
1.21 In LEMON we use C++ templates heavily, thus compilation takes a
1.22 considerable amount of time and memory. So some decent box would be
1.23 -advantageous. But otherwise there are no special hardware requirements.
1.24 +advantageousm, but otherwise there are no special hardware requirements.
1.25
1.26 You will need a recent C++ compiler. Our primary target is the GNU C++
1.27 Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
1.28 -Compiler (icc) and Microsoft Visual C++ .NET 2003, 2005.
1.29 -If you want to develop with LEMON under Windows you could consider
1.30 -using Cygwin.
1.31 +Compiler (icc) and Microsoft Visual C++ (on Windows).
1.32 +If you want to develop with LEMON under Windows, you can use a Windows
1.33 +installer or you can consider using Cygwin.
1.34
1.35 In this description we will suppose a Linux environment and GNU C++ Compiler.
1.36 +If you would like to develop under Windows and use a Windows installer,
1.37 +you could skip the following sections and continue reading \ref hello_lemon.
1.38 +However keep in mind that you have to make appropriate steps instead of
1.39 +the instructions detailed here to be able to compile the example code
1.40 +with your compiler.
1.41
1.42 \subsection requirements_lp LP Solver Requirements
1.43
1.44 The LEMON LP solver interface can use the GLPK (GNU Linear Programming
1.45 -Kit), CPLEX (was tested with CPLEX 7.5) and SoPlex solver. If you want
1.46 -to use it you will need at least one of these. See \ref configure_flags
1.47 -how to enable these at compile time.
1.48 +Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
1.49 +least one of these.
1.50 +See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.
1.51
1.52 \section download_lemon How to Download LEMON
1.53
1.54 -You can download LEMON from the LEMON web site:
1.55 -<a href="http://lemon.cs.elte.hu/">https://lemon.cs.elte.hu/</a>.
1.56 -There you will find released versions in form of <tt>.tar.gz</tt> files.
1.57 +You can download LEMON from our web site:
1.58 +<a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.
1.59 +There you will find released versions in form of <tt>.tar.gz</tt> files
1.60 +(and Windows installers).
1.61 If you want a developer version (for example you want to contribute in
1.62 -developing the library LEMON) then you might want to use our Mercurial
1.63 -repository. This case is detailed later, so from now on we suppose that
1.64 -you downloaded a <tt>.tar.gz</tt> file.
1.65 +developing LEMON) then you might want to use our Mercurial repository.
1.66 +This case is detailed \ref hg_checkout "later", so from now on we
1.67 +suppose that you downloaded a <tt>.tar.gz</tt> file.
1.68
1.69 \section install_lemon How to Install LEMON
1.70
1.71 @@ -117,7 +123,7 @@
1.72 make check
1.73 \endverbatim
1.74 This step is optional, but recommended. It runs the test programs that
1.75 -we developed for LEMON to check whether the library works properly on
1.76 +have been developed for LEMON to check whether the library works properly on
1.77 your platform.
1.78
1.79 \verbatim
1.80 @@ -130,22 +136,21 @@
1.81 non-default location.
1.82
1.83 Several other configure flags can be passed to <tt>./configure</tt>.
1.84 -For more information see <tt>./configure --help</tt> and the INSTALL
1.85 -file in the install directory.
1.86 +For more information see the <b><tt>INSTALL</tt></b> file.
1.87
1.88 \section hg_checkout How to Checkout LEMON from our Mercurial Repository
1.89
1.90 -You can obtain the latest version of LEMON from our Mercurial repository.
1.91 -To do this issue the following command:
1.92 +You can obtain the latest (developer) version of LEMON from our Mercurial
1.93 +repository. To do this issue the following command.
1.94 \verbatim
1.95 -hg clone http://lemon.cs.elte.hu/hg/lemon lemon-src
1.96 +hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
1.97 \endverbatim
1.98
1.99 \section hg_compile How to Compile the Source from the Repository
1.100
1.101 You can compile the code from the repository similarly to the packaged
1.102 -version, but you will need to run <b><tt>autoreconf -vif</tt></b> or
1.103 -<b><tt>./bootstrap</tt></b> in some older environment before
1.104 +version, but you will need to run <b><tt>autoreconf -vif</tt></b>
1.105 +(or <b><tt>./bootstrap</tt></b> in some older environment) before
1.106 <tt>./configure</tt>. See <tt>./configure --help</tt> for options.
1.107 For bootstrapping you will need the following tools:
1.108
1.109 @@ -157,4 +162,105 @@
1.110 To generate the documentation, run <tt>make html</tt>.
1.111 You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.
1.112
1.113 +\section hello_lemon Compile Your First Code
1.114 +
1.115 +If you have installed LEMON on your system you can paste the following
1.116 +code segment into a file called <tt>hello_lemon.cc</tt> to have a first
1.117 +working program that uses LEMON.
1.118 +
1.119 +\dontinclude hello_lemon.cc
1.120 +\skip #include
1.121 +\until }
1.122 +
1.123 +First let us briefly explain how this example program works.
1.124 +(The used notions will be discussed in detail in the following chapter.)
1.125 +
1.126 +After some convenience typedefs we create a directed graph (\e digraph)
1.127 +and add some nodes and arcs to it.
1.128 +ListDigraph is one of the digraph classes implemented in LEMON.
1.129 +It is based on linked lists, therefore iterating through its nodes and
1.130 +arcs is fast.
1.131 +
1.132 +Then we iterate through all nodes of the digraph and print their unique
1.133 +IDs. We use a constructor of the node iterator to initialize it to the
1.134 +first node.
1.135 +The <tt>operator++</tt> is used to step to the next node. After the last
1.136 +node the iterator becomes invalid (i.e. it is set to \c INVALID).
1.137 +This is what we exploit in the stop condition.
1.138 +We iterate through all arcs of the digraph very similarly and print the
1.139 +IDs of their source (tail) and target (head) nodes using the \c source()
1.140 +and \c target() member functions.
1.141 +
1.142 +After that we create an arc map, which is actually a mapping that assigns
1.143 +an \c int value (length) to each arc, and we set this value for each arc.
1.144 +Finally we iterate through all arcs again and print their lengths.
1.145 +
1.146 +Now let's compile this simple example program.
1.147 +
1.148 +\subsection hello_lemon_system If LEMON is Installed System-Wide
1.149 +
1.150 +If your installation of LEMON into directory \c /usr/local was
1.151 +successful, then it is very easy to compile this program with the
1.152 +following command (the argument <tt>-lemon</tt> tells the compiler
1.153 +that we are using the installed LEMON):
1.154 +
1.155 +\verbatim
1.156 +g++ hello_lemon.cc -o hello_lemon -lemon
1.157 +\endverbatim
1.158 +
1.159 +As a result you will get the exacutable \c hello_lemon in the current
1.160 +directory, which you can run by the following command.
1.161 +
1.162 +\verbatim
1.163 +./hello_lemon
1.164 +\endverbatim
1.165 +
1.166 +\subsection hello_lemon_user If LEMON is Installed User-Local
1.167 +
1.168 +Compiling the code is a bit more difficult if you installed LEMON
1.169 +user-local into a directory (e.g. <tt>~/lemon</tt>) or if you just
1.170 +skipped the step <tt>make install</tt>.
1.171 +You have to issue a command like this.
1.172 +
1.173 +\verbatim
1.174 +g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs
1.175 +\endverbatim
1.176 +
1.177 +\subsubsection hello_lemon_pkg_config Use pkg-config
1.178 +
1.179 +\todo Write this sub-subsection (\ref hello_lemon_pkg_config).
1.180 +
1.181 +If everything has gone well, then our program prints out the followings.
1.182 +
1.183 +\verbatim
1.184 +Hello World!
1.185 +This is LEMON library here. We have a direceted graph.
1.186 +
1.187 +Nodes: 3 2 1 0
1.188 +Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)
1.189 +
1.190 +There is a map on the arcs (length):
1.191 +
1.192 +length(2,3)=10
1.193 +length(1,3)=25
1.194 +length(1,2)=5
1.195 +length(0,2)=20
1.196 +length(0,1)=10
1.197 +\endverbatim
1.198 +
1.199 +You may note that iterating through the nodes and arcs is done in the
1.200 +reverse order compared to the creating order (the IDs are in decreasing
1.201 +order).
1.202 +This is due to implementation aspects, that may differ at other graph
1.203 +types, moreover it may be changed in the next releases.
1.204 +Thus you should not exploit this method in any way, you should not
1.205 +suppose anything about the iteration order.
1.206 +
1.207 +If you managed to compile and run this example code without any problems,
1.208 +you can go on reading this tutorial to get to know more features and tools
1.209 +of LEMON.
1.210 +Otherwise if you encountered problems that you did not manage to solve,
1.211 +do not hesitate to
1.212 +<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>.
1.213 +
1.214 */
2.1 --- a/intro.dox Thu Oct 23 14:06:53 2008 +0200
2.2 +++ b/intro.dox Thu Oct 23 14:07:30 2008 +0200
2.3 @@ -21,25 +21,35 @@
2.4
2.5 \section intro_lemon What is LEMON
2.6
2.7 -LEMON stands for <b>L</b>ibrary of <b>E</b>fficient <b>M</b>odels and
2.8 +<b>LEMON</b> stands for <b>L</b>ibrary of <b>E</b>fficient <b>M</b>odels and
2.9 <b>O</b>ptimization in <b>N</b>etworks. It is a C++ template
2.10 -library aimed at combinatorial optimization tasks which often involve
2.11 -in working with graphs.
2.12 +library aimed at combinatorial optimization tasks, especially those
2.13 +working with graphs and networks.
2.14
2.15 <b>LEMON is an <a class="el" href="http://opensource.org/">open source</a>
2.16 project.
2.17 You are free to use it in your commercial or non-commercial applications
2.18 -under very permissive \ref license "license terms".
2.19 -</b>
2.20 +under very permissive \ref license "license terms".</b>
2.21 +
2.22 +This library helps to write programs that solve optimization problems
2.23 +that arise frequently when designing and testing certain networks,
2.24 +for example in telecommunication, computer networks, logistics, scheduling,
2.25 +and other areas.
2.26 +A very natural way of modelling these networks is by means of a graph.
2.27 +Generally if you want to write any program that works with graphs,
2.28 +then you might find it useful and convenient to use LEMON.
2.29 +
2.30 +For more information visit the LEMON web site:
2.31 +<a href="http://lemon.cs.elte.hu/"><b>http://lemon.cs.elte.hu/</b></a>.
2.32
2.33 \section intro_tutorial LEMON Tutorial
2.34
2.35 This tutorial introduces the reader to the basic concepts and features of
2.36 -LEMON, and there are some sections about advanced topics showing the power
2.37 -of the various tools implemented in the library.
2.38 +LEMON, and there are also some sections about advanced topics showing the
2.39 +power of various tools implemented in the library.
2.40
2.41 -After getting familiar with the basic concepts you may start using LEMON
2.42 -with the help of the detailed documentation (that can also be used as a
2.43 -reference manual).
2.44 +After getting familiar with the basics of the library, you may start using
2.45 +LEMON with the help of the detailed documentation (that can also be used
2.46 +as a reference manual).
2.47
2.48 */