COIN-OR::LEMON - Graph Library

source: lemon-tutorial/getting_started.dox @ 6:da96f28684f7

Last change on this file since 6:da96f28684f7 was 6:da96f28684f7, checked in by Peter Kovacs <kpeter@…>, 12 years ago

Extend and improve the first two chapters

File size: 9.5 KB
Line 
1/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 *
3 * This file is a part of LEMON, a generic C++ optimization library.
4 *
5 * Copyright (C) 2003-2008
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 *
9 * Permission to use, modify and distribute this software is granted
10 * provided that this copyright notice appears in all copies. For
11 * precise terms see the accompanying LICENSE file.
12 *
13 * This software is provided "AS IS" with no warranty of any kind,
14 * express or implied, and with no claim as to its suitability for any
15 * purpose.
16 *
17 */
18
19/**
20\page getting_started Getting Started
21
22In this page we detail how to start using LEMON, from downloading it to
23your computer, through the steps of installation, to showing a simple
24"Hello World" type program that already uses LEMON. We assume that you
25have a basic knowledge of your operating system and C++ programming
26language. The procedure is pretty straightforward, but if you have any
27difficulties do not hesitate to
28<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
29
30\section requirements_lemon Hardware and Software Requirements
31
32In LEMON we use C++ templates heavily, thus compilation takes a
33considerable amount of time and memory. So some decent box would be
34advantageousm, but otherwise there are no special hardware requirements.
35
36You will need a recent C++ compiler. Our primary target is the GNU C++
37Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
38Compiler (icc) and Microsoft Visual C++ (on Windows).
39If you want to develop with LEMON under Windows, you can use a Windows
40installer or you can consider using Cygwin.
41
42In this description we will suppose a Linux environment and GNU C++ Compiler.
43If you would like to develop under Windows and use a Windows installer,
44you could skip the following sections and continue reading \ref hello_lemon.
45However keep in mind that you have to make appropriate steps instead of
46the instructions detailed here to be able to compile the example code
47with your compiler.
48
49\subsection requirements_lp LP Solver Requirements
50
51The LEMON LP solver interface can use the GLPK (GNU Linear Programming
52Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
53least one of these.
54See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.
55
56\section download_lemon How to Download LEMON
57
58You can download LEMON from our web site:
59<a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.
60There you will find released versions in form of <tt>.tar.gz</tt> files
61(and Windows installers).
62If you want a developer version (for example you want to contribute in
63developing LEMON) then you might want to use our Mercurial repository.
64This case is detailed \ref hg_checkout "later", so from now on we
65suppose that you downloaded a <tt>.tar.gz</tt> file.
66
67\section install_lemon How to Install LEMON
68
69In order to install LEMON you have to do the following steps.
70
71Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x, \c y
72and \c z are numbers indicating the version of the library, in our example
73we will have <tt>lemon-1.0.tar.gz</tt>) and issue the following commands:
74
75\verbatim
76tar xvzf lemon-1.0.tar.gz
77cd lemon-1.0
78./configure
79make
80make check    # This is optional, but recommended. It runs a bunch of tests.
81make install
82\endverbatim
83
84These commands install LEMON under \c /usr/local (you will
85need root privileges to be able to install to that
86directory). If you want to install it to some other place, then
87pass the \c --prefix=DIRECTORY flag to <tt>./configure</tt>, for example:
88
89\verbatim
90./configure --prefix=/home/username/lemon
91\endverbatim
92
93In what follows we will assume that you were able to install to directory
94\c /usr/local, otherwise some extra care is to be taken to use the library.
95
96We briefly explain these commands below.
97
98\verbatim
99tar xvzf lemon-1.0.tar.gz
100\endverbatim
101This command untars the <tt>tar.gz</tt> file into a directory named
102<tt>lemon-1.0</tt>.
103
104\verbatim
105cd lemon-1.0
106\endverbatim
107This command enters the directory.
108
109\verbatim
110./configure
111\endverbatim
112This command runs the configure shell script, which does some checks and
113creates the makefiles.
114
115\verbatim
116make
117\endverbatim
118This command compiles the non-template part of LEMON into <tt>libemon.a</tt>
119file. It also compiles the programs in the tools and demo subdirectories
120when enabled.
121
122\verbatim
123make check
124\endverbatim
125This step is optional, but recommended. It runs the test programs that
126have been developed for LEMON to check whether the library works properly on
127your platform.
128
129\verbatim
130make install
131\endverbatim
132This command will copy the directory structure to its final destination
133(e.g. to \c /usr/local) so that your system can access it.
134This command should be issued as "root", unless you provided a
135\c --prefix switch to the \c configure to install the library in
136non-default location.
137
138Several other configure flags can be passed to <tt>./configure</tt>.
139For more information see the <b><tt>INSTALL</tt></b> file.
140
141\section hg_checkout How to Checkout LEMON from our Mercurial Repository
142
143You can obtain the latest (developer) version of LEMON from our Mercurial
144repository. To do this issue the following command.
145\verbatim
146hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
147\endverbatim
148
149\section hg_compile How to Compile the Source from the Repository
150
151You can compile the code from the repository similarly to the packaged
152version, but you will need to run <b><tt>autoreconf -vif</tt></b>
153(or <b><tt>./bootstrap</tt></b> in some older environment) before
154<tt>./configure</tt>. See <tt>./configure --help</tt> for options.
155For bootstrapping you will need the following tools:
156
157 - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
158 - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
159 - <a href="http://www.gnu.org/software/libtool/">libtool</a>
160 - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
161
162To generate the documentation, run <tt>make html</tt>.
163You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.
164
165\section hello_lemon Compile Your First Code
166
167If you have installed LEMON on your system you can paste the following
168code segment into a file called <tt>hello_lemon.cc</tt> to have a first
169working program that uses LEMON.
170
171\dontinclude hello_lemon.cc
172\skip #include
173\until }
174
175First let us briefly explain how this example program works.
176(The used notions will be discussed in detail in the following chapter.)
177
178After some convenience typedefs we create a directed graph (\e digraph)
179and add some nodes and arcs to it.
180ListDigraph is one of the digraph classes implemented in LEMON.
181It is based on linked lists, therefore iterating through its nodes and
182arcs is fast.
183
184Then we iterate through all nodes of the digraph and print their unique
185IDs. We use a constructor of the node iterator to initialize it to the
186first node.
187The <tt>operator++</tt> is used to step to the next node. After the last
188node the iterator becomes invalid (i.e. it is set to \c INVALID).
189This is what we exploit in the stop condition.
190We iterate through all arcs of the digraph very similarly and print the
191IDs of their source (tail) and target (head) nodes using the \c source()
192and \c target() member functions.
193
194After that we create an arc map, which is actually a mapping that assigns
195an \c int value (length) to each arc, and we set this value for each arc.
196Finally we iterate through all arcs again and print their lengths.
197
198Now let's compile this simple example program.
199
200\subsection hello_lemon_system If LEMON is Installed System-Wide
201
202If your installation of LEMON into directory \c /usr/local was
203successful, then it is very easy to compile this program with the
204following command (the argument <tt>-lemon</tt> tells the compiler
205that we are using the installed LEMON):
206
207\verbatim
208g++ hello_lemon.cc -o hello_lemon -lemon
209\endverbatim
210
211As a result you will get the exacutable \c hello_lemon in the current
212directory, which you can run by the following command.
213
214\verbatim
215./hello_lemon
216\endverbatim
217
218\subsection hello_lemon_user If LEMON is Installed User-Local
219
220Compiling the code is a bit more difficult if you installed LEMON
221user-local into a directory (e.g. <tt>~/lemon</tt>) or if you just
222skipped the step <tt>make install</tt>.
223You have to issue a command like this.
224
225\verbatim
226g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs
227\endverbatim
228
229\subsubsection hello_lemon_pkg_config Use pkg-config
230
231\todo Write this sub-subsection (\ref hello_lemon_pkg_config).
232
233If everything has gone well, then our program prints out the followings.
234
235\verbatim
236Hello World!
237This is LEMON library here. We have a direceted graph.
238
239Nodes: 3 2 1 0
240Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)
241
242There is a map on the arcs (length):
243
244length(2,3)=10
245length(1,3)=25
246length(1,2)=5
247length(0,2)=20
248length(0,1)=10
249\endverbatim
250
251You may note that iterating through the nodes and arcs is done in the
252reverse order compared to the creating order (the IDs are in decreasing
253order).
254This is due to implementation aspects, that may differ at other graph
255types, moreover it may be changed in the next releases.
256Thus you should not exploit this method in any way, you should not
257suppose anything about the iteration order.
258
259If you managed to compile and run this example code without any problems,
260you can go on reading this tutorial to get to know more features and tools
261of LEMON.
262Otherwise if you encountered problems that you did not manage to solve,
263do not hesitate to
264<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>.
265
266*/
Note: See TracBrowser for help on using the repository browser.