source: releases/5.6.5/INSTALL

Last change on this file was 2316, checked in by tkr, 3 years ago

Syncing with trunk at r2315

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.4 KB
Line 
1This file is written in the markup language of the TRAC wiki on which it is
2maintained. Please see the on-line version here
3
4https://projects.coin-or.org/SYMPHONY/wiki/BuildAndInstall
5
6= BUILDING AND INSTALLING SYMPHONY Version 5.6 =
7
8The following are brief instructions that should be sufficient to install
9SYMPHONY with default configuration settings in most cases. For more detailed
10installation instructions and for more information on custom configurations,
11please see the SYMPHONY [ user's manual].
12
13== Building SYMPHONY in Unix-like environments (UNIX/LINUX/CYGWIN/MINGW/OSX) ==
14
15SYMPHONY uses the COIN-OR build system and the GNU autotools to automate the
16build process. The build process should therefore be identical in all
17Unix-like environments. These instructions will lead you through the steps
18required to compile SYMPHONY as a generic MILP solver. This process will
19create (1) a generic callable library that allows SYMPHONY to be called from
20an application and (2) an executable that can be used as a stand-alone
21application to solve MILPs written in either MPS or GMPL file format. SYMPHONY
22can be further customized by implementing one of more than 50 callback
23functions that change SYMPHONY's default execution of its algorithm. For
24information on customizing SYMPHONY using callbacks, a quick start guide is
25provided below.
26
27=== DOWNLOADING ===
28
29You can obtain the SYMPHONY source code either via the subversion repository
30or in the form of archived release. The recommended method in Unix is to use
31subversion because it makes it easier to obtain updates. In a Unix-like
32environment (such as Linux or CYGWIN), the following command may be used to
33obtain SYMPHONY from source using SVN in most cases:
34
35{{{svn co https://projects.coin-or.org/svn/SYMPHONY/stable/5.6 SYMPHONY-5.6}}}
36
37Alternatively, you can download release versions of the source code from the
38[http://www.coin-or.org/download/source/SYMPHONY download page] of COIN-OR. If
39the code is obtained as a tarball, unpack the distribution with
40
41{{{tar -xzf SYMPHONY-XX.tgz"}}}
42
43where XX is the version number. This will create a subdirectory called
44SYMPHONY-XX containing the distribution.
45
46=== CONFIGURING ===
47
48The first step is to run a configuration script that will allow the
49compilation process to be customized for your environment. to perform this
50step, switch into the root directory of the distribution and type
51
52{{{./configure}}}
53
54This will set up the default configuration files. If you want to override the
55default settings, you can either run the configuration script with
56command-line options or else modify the options in the file
57'share/config.site'. For instance, you might want to specify the LP solver to
58be used (Clp is the default). A list of options together with brief
59explanations can be seen both in the file 'share/config.site' and by typing
60
61{{{./configure --help=recursive}}}
62
63In order to enable or disable an option, either update the file
64{{{share/config.site}}} or add the option as an argument to configuration
65script. As an instance for the second case, running
66
67{{{./configure --enable-debug}}}
68
69will set the configuration to compile the source files with debugging flag.
70
71In order to read GMPL files, you need to have the GLPK package install. To
72install it automatically, run the {{{get.Glpk}}} script in the
73{{{ThirdParty/Glpk}}} directory. After that, Glpk should be built and linked
74automatically, enabling the ability to read GMPL files.
75
76It is possible to use compilers other than the default (which is g++). For
77example, to perform at automated build of SYMPHONY using the MSVC++ compiler
78{{{cl}}} with GNU autotools in the CYGWIN environment configure with
79
80{{{./configure --enable-msvc}}}
81
82Please see further details on building in this configuration [ here]
83
84=== BUILDING ===
85
86  1. After configuring, the code can be built by typing the commands
87
88{{{
89make
90make install
91}}}
92
93This will first create the required libraries and binaries and then will
94install SYMPHONY. By default, the library 'libSym' and the executable
95{{{symphony}}} will be installed to the {{{lib/}}} and {{{bin/}}} directories.
96
97  2. The SYMPHONY library, together with the header files in the subdirectory
98  {{{include/}}}, can then be used to call SYMPHONY from any C/C++ code. The
99  API for this is described in the user's manual. The executable can also be
100  used for solving generic MILP problems in MPS or GMPL format. In order to
101  read GMPL files, you need to have the GLPK package install. To install it
102  automatically, run the {{{get.Glpk}}} script in the ThirdParty/Glpk
103  directory. After that, Glpk should be built and linked automatically,
104  enabling the ability to read GMPL files.
105
106For a more powerful modeling interface, FlopC++ can also be used to obtain a
107capability similar to ILOG's Concert technology for building math programming
108models (see SYMPHONY/Examples/FLOPC++).
109
110If you are planning to use the interactive optimizer, it is recommended to run
111the configuration script with
112
113{{{./configure --enable-gnu-packages}}}
114
115This will allow the interactive shell to be able to behave exactly like a
116Linux terminal command line, i.e., it will keep the history of the used
117commands, will complete the input word to possible commands, etc. Make sure
118that you have the needed package ({{{readline.h}}} and {{{history.h}}} include
119files and their libraries) on the system files path.
120
121  3. To test SYMPHONY after building, type
122
123{{{make test}}}
124
125to execute an automated unit test. To test out the optimizer manually. a
126sample MPS file called {{{sample.mps}}} and a sample GMPL/AMPL file called
127{{{sample.mod}}} together with its data file {{{sample.dat}}} are included
128with the distribution. You can use either the command-line or the interactive
129optimizer. To solve the sample MPS model, type
130
131{{{bin/symphony -F SYMPHONY/Datasets/sample.mps}}}
132
133To solve the GMPL model, use the "-F" switch to specify the file name and the
134"-D" for the data file name if the input is in GMPL/AMPL format, i.e., type
135
136{{{bin/symphony -F SYMPHONY/Datasets/sample.mod -D SYMPHONY/Datasets/sample.dat}}}
137
138For more MPS data files for further testing, see the MIPLIB library in the
139{{{Data/Sample}}} subdirectory. To run the interactive optimizer, execute
140SYMPHONY without any command-line arguments, i.e., type
141
142{{{bin/symphony}}}
143
144and then type {{{help}}} or {{{?}}} to see a list of available commands.
145
146  4. After the SYMPHONY library and the executable are compiled and tested,
147  you can type
148
149{{{make clean}}}
150
151if you want to save disk space.
152
153  5. That's it! Now you are ready to use SYMPHONY callable library or solve
154  generic MILP problems through the executable.
155
156=== SHARED MEMORY PARALLEL ===
157
158 1. To compile a shared memory version of SYMPHONY, simply use an OpenMP compliant
159 compiler. Version \VER\  builds with OpenMP support enabled automatically when
160 the compiler provides it. This should be the case for all recent versions of
161 gcc and recent Microsoft compilers. Clang on OS X does not support OpenMP,
162 though it is possible to build a version that does yourself. You can manually
163 enable or disable OpenMP support with configure options by doing, e.g.,
164
165 {{{./configure --enable-openmp}}}
166
167 In the Microsoft Visual Studio, enable OpenMP
168 support in the properties for the SYMPHONY projects (it doesn't need to be
169 enabled for the dependent projects). In a future version, this will also be
170 made the default.
171
172 2. Follow the instructions above for building and testing.
173
174 3. To invoke SYMPHONY from the command-line with multiple threads, specify the
175 number of \emph{additional} worker threads with the \code{-p} option, i.e.,
176 invoking SYMPHONY with
177
178 {{{bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps}}}
179
180 will utilize two worker threads to process subproblems in parallel.
181 When more than 1 thread is used, the first thread is the ``master''
182 thread and only prints out periodic status messages, as well as doing some
183 bookkeeping work. Therefore, it is recommended to always use at least one
184 worker thread (\code{-p 1}}). Starting in version 5.6.0, the number of
185 threads used is automatically set equal to the number of available cores if no
186 option is specified. For a fully sequential run with just one thread, invoke
187 SYMPHONY with
188
189 {{{bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps}}}
190
191=== DISTRIBUTED PARALLEL ===
192
193 1. If you wish to compile a distributed version of the code, first make sure
194 you have PVM installed. You can obtain it from http://www.csm.ornl.gov/pvm/.
195
196 2. To configure for a parallel build, invoke the configuration script as
197 follows:
198
199{{{./configure --with-pvm}}}
200
201Be sure that PVM is installed either in system path or that you have the
202environment variable PVM_ROOT set properly. Note that there are a number of
203different parallel configurations. The default configuration is to build two
204parallel modules. The first one consists of the master, tree management, and
205cut management modules, while the second one consists of the node processing,
206and cut generation modules. For other configuration options, see the
207{{{share/config.site file}}}
208
209 3. Follow the build instructions above to build the code. Note that this will
210 also compile the sequential version.
211
212 4. Make sure there are links from your {{{$HOME/pvm3/bin/$PVM_ARCH/}}}
213 subdirectory to each of the executables in your {{{bin/' directory}}} This is
214 required by PVM.
215
216 5. Start the PVM daemon by typing {{{pvm}}} on the command line and then
217 typing {{{quit}}}.
218
219 6. As above, test SYMPHONY using the sample MPS file called {{{sample.mps}}}
220 included with the distribution. To specify the file name, use the {{{-F}}}
221 command-line option, i.e., in the root directory, type
222
223{{{bin/symphony_m$(EXT) -F SYMPHONY/Datasets/sample.mps}}}
224
225where {{{$(EXT)}}} is an extension to be added according to the chosen module
226dependencies. To obtain more MPS data files for further testing, download the
227MIPLIB library.
228
229=== BUILDING APPLICATIONS ===
230
231 1. In order to compile SYMPHONY's applications, you must first compile the
232 application-specific library with
233
234{{{ ./configure --with-application make make install }}}
235
236This will create the application library called {{{libSymAppl}}} to be used
237while building custom applications. Note that the sequential version library
238and executable will also be made and installed.
239
240 2. After building the library, go to one of the application subdirectories in
241the {{{SYMPHONY/Applications/}}} directory and type {{{make}}} there. For more
242information, including the parallel configuration instructions, see the
243INSTALL file of the corresponding application.
244
245== COMPILING The SYMPHONY Library and Executable (Microsoft Windows) ==
246
247Here is a sketch outline of how to compile SYMPHONY in Microsoft Windows.
248These instructions will lead you through the steps required to compile
249SYMPHONY as a generic MILP solver. This process will create * a generic
250callable library that allows SYMPHONY to be called from an application and *
251an executable that can be used as a stand-alone application to solve MILPs
252written in either MPS, LP, or GMPL file format. SYMPHONY can be further
253customized by implementing one of more than 50 callback functions that change
254SYMPHONY's default execution of its algorithm. For information on customizing
255SYMPHONY using callbacks, a quick start guide is provided below. Note that in
256the Windows version, detailed timing information is not currently provided.
257
258First, obtain the source code as described above. Unpack the archive to create
259the directory SYMPHONY-XX. You now have three options. You can either build
260using the MSVC++ IDE, build on the command-line with MSVC++ executable, or use
261the NMAKE utility.
262
263== Building With the MSVC++ IDE ==
264
265These instructions are for MSVC++ Version 10. Instructions for other versions
266should be similar.
267
268 1. Go to {{{SYMPHONY/MSVisualStudio/v10}}} directory and open the solution
269 file {{{symphony.sln}}}.
270
271 1. Note that there are a number of additional preprocessor definitions that
272 control the functionality of SYMPHONY. These definitions are described in
273 {{{sym.mak}}}, a Unix-style makefile included in the distribution. To enable
274 the functionality associated with a particular definition, simply add it to
275 the list of definitions of {{{libSymphony}}} project together with the
276 required libraries and paths. For instance, if you want to enable GMPL reader
277 option, you need to * add the directory of the header files of GLPK to the
278 include files path * add {{{USE_GLPMPL}}} to the defines * add the GLPK
279 library to the solution
280
281 1. Make sure that the project {{{symphony}}} is set as the startup project by
282 choosing "Set as Startup Project" from the Project menu after selecting the
283 symphony project in the Solution Explorer. Choose {{{Build Solution}}} from
284 the {{{Build}}} menu. This should successfully build the SYMPHONY library and
285 the corresponding executable.
286
287 1. To test the executable, go to the {{{Debug}}} tab and choose {{{Start
288 Without Debugging.}}} and then type {{{help}}} or {{{?}}} to see a list of
289 available commands.
290
291== Building in a Windows Terminal ==
292
293These instructions are for MSVC++ Version 10. Instructions for other versions
294should be similar.
295
296 1. Open a command line terminal. Go to 'SYMPHONY/MSVisualStudio/v10'
297 directory and type
298
299 {{{devenv symphony.sln /Build "Debug|Win32}}}
300
301This will create the 32-bit debug version of SYMPHONY. You can build 64-bit
302with
303
304{{{devenv symphony.sln /Build "Debug|x64"}}}
305
306For each command, the library {{{libSymphony.lib}}} and the executable
307{{{symphony}}} will be created in directories according to platform and
308configuration. The library, together with the header files in
309{{{SYMPHONY\include\}}}, can then be used to call SYMPHONY from any C/C++
310code. The API for calling SYMPHONY is described in the user's manual.
311
312 1. To test the executable, type
313
314 {{{symphony.exe -F ..\..\SYMPHONY\Datasets\sample.mps}}}
315
316In the appropriate directory. If you want to use the interactive optimizer,
317simply type
318
319{{{symphony.exe}}}
320
321and then type {{{help}}} or {{{?}}} to see a list of available commands.
322
3233. If SYMPHONY is modified, type
324
325 {{{devenv symphony.sln /Rebuild "Debug|Win32"}}}
326
327in order to clean and rebuild everything.
328
329== Building With the MSVC++ compiler in CYGWIN ==
330
331It is possible to perform at automated build of SYMPHONY using the MSVC++
332compiler {{{cl}}} with GNU autotools in the CYGWIN environment. To do so,
333follow the instructions for building in Unix-like environments, except when
334configuring, use the command
335
336 ./configure --enable-msvc
337
338== Building With the NMAKE Utility ==
339
340Note: the {{{sym.mak}}} file is no longer maintained, but may work.
341
342 1. Go to {{{MSVisualStudio}}} directory and edit the {{{sym.mak}}} makefile
343to reflect your environment. This involves specifying the LP solver to be
344used, assigning some variables and setting various paths. Only minor edits
345should be required. An explanation of what has to be set is contained in the
346comments in the makefile. Note that, you have to first create the COIN
347libraries Cgl, Clp, Osi, OsiClp and CoinUtils.
348
349 1. Once configuration is done, open a command line terminal and type
350
351{{{nmake sym.mak}}}
352
353This will make the SYMPHONY library {{{libSymphony.lib}}} and the executable
354{{{symphony}}} in {{{Debug}}} directory. The library, together with the header
355files in {{{SYMPHONY\include\}}}, can then be used to call SYMPHONY from any
356C/C++ code. The API for calling SYMPHONY is described in the user's manual.
357
358 3. To test the executable, type
359
360 {{{symphony.exe -F ..\..\SYMPHONY\Datasets\sample.mps}}}
361
362in the output directory. If you want to use the interactive optimizer, simply
363type
364
365 {{{symphony.exe}}}
366
367and then type {{{help}}} or {{{?}}} to see a list of available commands.
368 
Note: See TracBrowser for help on using the repository browser.