INSTALL

This file is written in the markup language of the TRAC wiki on which it is
maintained. Please see the on-line version here

https://projects.coin-or.org/SYMPHONY/wiki/BuildAndInstall

= BUILDING AND INSTALLING SYMPHONY Version 5.6 =

The following are brief instructions that should be sufficient to install
SYMPHONY with default configuration settings in most cases. For more detailed
installation instructions and for more information on custom configurations,
please see the SYMPHONY [ user's manual].

== Building SYMPHONY in Unix-like environments (UNIX / LINUX / CYGWIN / MSys / OSX) ==

For more detailed information on MSys and CYGWIN installs, see below.

SYMPHONY uses the COIN-OR build system and the GNU autotools to automate the
build process. The build process should therefore be identical in all
Unix-like environments. These instructions will lead you through the steps
required to compile SYMPHONY as a generic MILP solver. This process will
create (1) a generic callable library that allows SYMPHONY to be called from
an application and (2) an executable that can be used as a stand-alone
application to solve MILPs written in either MPS or GMPL file format. SYMPHONY
can be further customized by implementing one of more than 50 callback
functions that change SYMPHONY's default execution of its algorithm. For
information on customizing SYMPHONY using callbacks, a quick start guide is
provided below.

=== DOWNLOADING SOURCE ===

You can obtain the SYMPHONY source code either via the subversion repository,
via Github, or in the form of archived release. The recommended method in Unix
is to use subversion because it makes it easier to obtain updates and to
download the correct versions of dependencies. In a Unix-like
environment (such as Linux or CYGWIN), the following command may be used to
obtain SYMPHONY from source using SVN in most cases:

{{{svn co https://projects.coin-or.org/svn/SYMPHONY/stable/5.6 SYMPHONY-5.6}}}

To obtain via git from github, you can do

{{{git clone --branch=stable/5.6 https://github.com/coin-or/SYMPHONY/ SYMPHONY-5.6}}}

Alternatively, you can download release versions of the source code from the
[http://www.coin-or.org/download/source/SYMPHONY download page] of COIN-OR. If
the code is obtained as a tarball, unpack the distribution with

{{{tar -xzf SYMPHONY-XX.tgz"}}}

where XX is the version number. This will create a subdirectory called
SYMPHONY-XX containing the distribution.

=== CONFIGURING ===

The first step is to run a configuration script that will allow the
compilation process to be customized for your environment. To perform this
step, first switch into the root directory

{{{
cd SYMPHONY-5.6
}}}

of the distribution and type.

If you checked out the git repo, you can then obtain the dependencies by 
typing the following (this is unnecessary with SVN).

{{{
git clone --branch=stable/0.8 https://github.com/coin-or-tools/BuildTools/
BuildTools/get.dependencies fetch
}}}

The finally, do

{{{
./configure
}}}

With git, you need to fetch the dependencies first.

This will set up the default configuration files. If you want to override the
default settings, you can either run the configuration script with
command-line options or else modify the options in the file
'share/config.site'. For instance, you might want to specify the LP solver to
be used (Clp is the default). A list of options together with brief
explanations can be seen both in the file 'share/config.site' and by typing

{{{
./configure --help=recursive
}}}

In order to enable or disable an option, either update the file
{{{share/config.site}}} or add the option as an argument to configuration
script. As an instance for the second case, running

{{{
./configure --enable-debug
}}}

will set the configuration to compile the source files with debugging flag.

In order to read GMPL files, you need to have the GLPK package install. To
install it automatically, run the {{{get.Glpk}}} script in the
{{{ThirdParty/Glpk}}} directory. After that, configure with the additional 
argument {{{--with-gmpl}}} and Glpk should be built and linked
automatically, enabling the ability to read GMPL files.

It is possible to use compilers other than the default (which is g++). For
example, to perform at automated build of SYMPHONY using the MSVC++ compiler
{{{cl}}} with GNU autotools in the CYGWIN environment configure with

{{{
./configure --enable-msvc
}}}

Please see further details on building in this configuration below.

=== BUILDING ===

  1. After configuring, the code can be built by typing the commands

   {{{
   make 
   make install
   }}}

  This will first create the required libraries and binaries and then will
  install SYMPHONY. By default, the library 'libSym' and the executable
  {{{symphony}}} will be installed to the {{{lib/}}} and {{{bin/}}} directories.

  2. The SYMPHONY library, together with the header files in the subdirectory
  {{{include/}}}, can then be used to call SYMPHONY from any C/C++ code. The
  API for this is described in the user's manual. The executable can also be
  used for solving generic MILP problems in MPS or GMPL format. In order to
  read GMPL files, you need to have the GLPK package install. To install it
  automatically, run the {{{get.Glpk}}} script in the ThirdParty/Glpk
  directory. After that, Glpk should be built and linked automatically,
  enabling the ability to read GMPL files.

  For a more powerful modeling interface, FlopC++ can also be used to obtain a
  capability similar to ILOG's Concert technology for building math programming
  models (see SYMPHONY/Examples/FLOPC++).

  If you are planning to use the interactive optimizer, it is recommended to run
  the configuration script with

  {{{./configure --enable-gnu-packages}}}

  This will allow the interactive shell to be able to behave exactly like a
  Linux terminal command line, i.e., it will keep the history of the used
  commands, will complete the input word to possible commands, etc. Make sure
  that you have the needed package ({{{readline.h}}} and {{{history.h}}} include
  files and their libraries) on the system files path.

  3. To test SYMPHONY after building, type

  {{{make test}}}

  to execute an automated unit test. To test out the optimizer manually. a
  sample MPS file called {{{sample.mps}}} and a sample GMPL/AMPL file called
  {{{sample.mod}}} together with its data file {{{sample.dat}}} are included
  with the distribution. You can use either the command-line or the interactive
  optimizer. To solve the sample MPS model, type

  {{{bin/symphony -F SYMPHONY/Datasets/sample.mps}}}

  To solve the GMPL model, use the "-F" switch to specify the file name and the
  "-D" for the data file name if the input is in GMPL/AMPL format, i.e., type

  {{{bin/symphony -F SYMPHONY/Datasets/sample.mod -D SYMPHONY/Datasets/sample.dat}}}

  For more MPS data files for further testing, see the MIPLIB library in the
  {{{Data/Sample}}} subdirectory. To run the interactive optimizer, execute
  SYMPHONY without any command-line arguments, i.e., type

  {{{bin/symphony}}}

  and then type {{{help}}} or {{{?}}} to see a list of available commands.

  4. After the SYMPHONY library and the executable are compiled and tested,
  you can type

  {{{make clean}}}

  if you want to save disk space.

  5. That's it! Now you are ready to use SYMPHONY callable library or solve
  generic MILP problems through the executable.

=== SHARED MEMORY PARALLEL ===

  1. To compile a shared memory version of SYMPHONY, simply use an OpenMP compliant
  compiler. Version \VER\  builds with OpenMP support enabled automatically when
  the compiler provides it. This should be the case for all recent versions of
  gcc and recent Microsoft compilers. Clang on OS X does not support OpenMP,
  though it is possible to build a version that does yourself. You can manually
  enable or disable OpenMP support with configure options by doing, e.g.,

  {{{./configure --enable-openmp}}}

  In the Microsoft Visual Studio, enable OpenMP
  support in the properties for the SYMPHONY projects (it doesn't need to be
  enabled for the dependent projects). In a future version, this will also be
  made the default.

  2. Follow the instructions above for building and testing.

  3. To invoke SYMPHONY from the command-line with multiple threads, specify the
  number of \emph{additional} worker threads with the \code{-p} option, i.e.,
  invoking SYMPHONY with 

  {{{bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps}}}

  will utilize two worker threads to process subproblems in parallel.
  When more than 1 thread is used, the first thread is the ``master''
  thread and only prints out periodic status messages, as well as doing some
  bookkeeping work. Therefore, it is recommended to always use at least one
  worker thread (\code{-p 1}}). Starting in version 5.6.0, the number of
  threads used is automatically set equal to the number of available cores if no
  option is specified. For a fully sequential run with just one thread, invoke
  SYMPHONY with 

  {{{bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps}}}

=== DISTRIBUTED PARALLEL ===

  1. If you wish to compile a distributed version of the code, first make sure
  you have PVM installed. You can obtain it from http://www.csm.ornl.gov/pvm/.

  2. To configure for a parallel build, invoke the configuration script as
  follows:

  {{{./configure --with-pvm}}}

  Be sure that PVM is installed either in system path or that you have the
  environment variable PVM_ROOT set properly. Note that there are a number of
  different parallel configurations. The default configuration is to build two
  parallel modules. The first one consists of the master, tree management, and
  cut management modules, while the second one consists of the node processing,
  and cut generation modules. For other configuration options, see the
  {{{share/config.site file}}}

  3. Follow the build instructions above to build the code. Note that this will
  also compile the sequential version.

  4. Make sure there are links from your {{{$HOME/pvm3/bin/$PVM_ARCH/}}}
  subdirectory to each of the executables in your {{{bin/' directory}}} This is
  required by PVM.

  5. Start the PVM daemon by typing {{{pvm}}} on the command line and then
  typing {{{quit}}}.

  6. As above, test SYMPHONY using the sample MPS file called {{{sample.mps}}}
  included with the distribution. To specify the file name, use the {{{-F}}}
  command-line option, i.e., in the root directory, type

  {{{bin/symphony_m$(EXT) -F SYMPHONY/Datasets/sample.mps}}}

  where {{{$(EXT)}}} is an extension to be added according to the chosen module
  dependencies. To obtain more MPS data files for further testing, download the
  MIPLIB library.

=== BUILDING APPLICATIONS ===

  1. In order to compile SYMPHONY's applications, you must first compile the
  application-specific library with

  {{{ 
  ./configure --with-application 
  make 
  make install 
  }}}

  This will create the application library called {{{libSymAppl}}} to be used
  while building custom applications. Note that the sequential version library
  and executable will also be made and installed.

  2. After building the library, go to one of the application subdirectories in
  the {{{SYMPHONY/Applications/}}} directory and type {{{make}}} there. For more
  information, including the parallel configuration instructions, see the
  INSTALL file of the corresponding application.

== COMPILING The SYMPHONY Library and Executable (Microsoft Windows) ==

  Here is a sketch outline of how to compile SYMPHONY in Microsoft Windows.
  These instructions will lead you through the steps required to compile
  SYMPHONY as a generic MILP solver. This process will create * a generic
  callable library that allows SYMPHONY to be called from an application and *
  an executable that can be used as a stand-alone application to solve MILPs
  written in either MPS, LP, or GMPL file format. SYMPHONY can be further
  customized by implementing one of more than 50 callback functions that change
  SYMPHONY's default execution of its algorithm. For information on customizing
  SYMPHONY using callbacks, a quick start guide is provided below. Note that in
  the Windows version, detailed timing information is not currently provided.

  First, obtain the source code as described above. Unpack the archive to create
  the directory SYMPHONY-XX. You now have three options. You can either build
  using the MSVC++ IDE, build on the command-line with MSVC++ executable, or use
  the NMAKE utility.

  The recommended and best-supported way of building in Windows is from a command
  prompt using the MSys2 shell. You can build with either the MSVC++ or the MinGW 
  compilers in this way. This gives you the most flexibility and power over the
  build options.

=== BUILDING WITH MSys2 or CYGWIN ===

  1. First, install either MSys2 or CYGWIN
    * To install MSys2, download the installer [https://msys2.github.io/ here]
    * To install CYGWIN, go [https://cygwin.com/install.html here]

  2. Modify your Windows path.
    * For Msys2, add the MSys2 {{{bin}}} {{{msys64\usr\bin}}} to your Windows {{{PATH}}}. 
    * For CYGWIN, add the CYGWIN {{{bin}}} directory to your Windows {{{PATH}}} (probably 
    {{{cygwin64\bin}}}).

  3. Open a Windows terminal.

  4. If building with the Visual Studio compiler, execute {{{vcvarsall.bat}}}.

  5. At the command prompt, type {{{bash}}}. 

  6. Install required packages:
    * For MSys2, at the {{{bash}}} prompt, do
    {{{
    pacman -S make wget tar patch dos2unix diffutils svn
    svn co https://projects.coin-or.org/svn/SYMPHONY/stable/5.6 SYMPHONY-5.6
    }}}
    * For CYGWIN, install gcc, gfortran, wget, tar, patch, dos2unix, and svn (and any other packages that seem to be missing)

  7. Then next
    * To build with the Visual Studio compiler, do
    {{{
    ./configure --build=x86_64-w64-mingw32 --enable-msvc
    make
    make install
    }}}
    * To build with the MinGW 32-bit compiler, do
    {{{
    pacman -S mingw-w64-i686-gcc mingw-w64-i686-gcc-fortran   
    export PATH=$PATH:/mingw32/bin
    ./configure --build=x86_64-w64-mingw32 --host=i686-w64-mingw32
    make
    make install
    }}}
    * To build with the MinGW 64-bit compiler, do
    {{{
    pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-gcc-fortran
    export PATH=$PATH:/mingw64/bin
    ./configure --build=x86_64-w64-mingw32 --host=x86_64-w64-mingw32
    make
    make install
    }}}
  Note that it is also possible to obtain SYMPHONY with git. See *Nix 
  instructions above for details on how to modify these instructions
  for that case.

  8. To test SYMPHONY after building, type

  {{{make test}}}

  to execute an automated unit test. To test out the optimizer manually. a
  sample MPS file called {{{sample.mps}}} and a sample GMPL/AMPL file called
  {{{sample.mod}}} together with its data file {{{sample.dat}}} are included
  with the distribution. You can use either the command-line or the interactive
  optimizer. To solve the sample MPS model, type

  {{{bin/symphony -F SYMPHONY/Datasets/sample.mps}}}

  For more MPS data files for further testing, see the MIPLIB library in the
  {{{Data/Sample}}} subdirectory. To run the interactive optimizer, execute
  SYMPHONY without any command-line arguments, i.e., type

  {{{bin/symphony}}}

  and then type {{{help}}} or {{{?}}} to see a list of available commands.

=== BUILDING WITH the MSVC++ IDE ===

  These instructions are for MSVC++ Version 10. Instructions for other versions
  should be similar. '''The MSVC++ are not regularly tested so please let us know
  if they are broken.'''

  1. Go to {{{SYMPHONY/MSVisualStudio/v10}}} directory and open the solution
  file {{{symphony.sln}}}.

  2. Note that there are a number of additional preprocessor definitions that
  control the functionality of SYMPHONY. These definitions are described in
  {{{sym.mak}}}, a Unix-style makefile included in the distribution. To enable
  the functionality associated with a particular definition, simply add it to
  the list of definitions of {{{libSymphony}}} project together with the
  required libraries and paths. For instance, if you want to enable GMPL reader
  option, you need to * add the directory of the header files of GLPK to the
  include files path * add {{{USE_GLPMPL}}} to the defines * add the GLPK
  library to the solution

  3. Make sure that the project {{{symphony}}} is set as the startup project by
  choosing "Set as Startup Project" from the Project menu after selecting the
  symphony project in the Solution Explorer. Choose {{{Build Solution}}} from
  the {{{Build}}} menu. This should successfully build the SYMPHONY library and
  the corresponding executable.

  4. To test the executable, go to the {{{Debug}}} tab and choose {{{Start
  Without Debugging.}}} and then type {{{help}}} or {{{?}}} to see a list of
  available commands.

=== BUILDING WITH VISUAL STUDIO FROM COMMAND LINE (deprecated) ===
  
These instructions are for MSVC++ Version 10. Instructions for other versions
should be similar.

  1. Open a command line terminal. Go to 'SYMPHONY/MSVisualStudio/v10'
  directory and type

  {{{devenv symphony.sln /Build "Debug|Win32}}}

  This will create the 32-bit debug version of SYMPHONY. You can build 64-bit
  with

  {{{devenv symphony.sln /Build "Debug|x64"}}}

  For each command, the library {{{libSymphony.lib}}} and the executable
  {{{symphony}}} will be created in directories according to platform and
  configuration. The library, together with the header files in
  {{{SYMPHONY\include\}}}, can then be used to call SYMPHONY from any C/C++
  code. The API for calling SYMPHONY is described in the user's manual.

  2. To test the executable, type

  {{{symphony.exe -F ..\..\SYMPHONY\Datasets\sample.mps}}}

  In the appropriate directory. If you want to use the interactive optimizer,
  simply type

  {{{symphony.exe}}}

  and then type {{{help}}} or {{{?}}} to see a list of available commands.

  3. If SYMPHONY is modified, type

  {{{devenv symphony.sln /Rebuild "Debug|Win32"}}}

  in order to clean and rebuild everything.

== BUILDING WITH THE NMAKE Utility (deprecated) ==

  Note: the {{{sym.mak}}} file is no longer maintained, but may work.

  1. Go to {{{MSVisualStudio}}} directory and edit the {{{sym.mak}}} makefile
  to reflect your environment. This involves specifying the LP solver to be
  used, assigning some variables and setting various paths. Only minor edits
  should be required. An explanation of what has to be set is contained in the
  comments in the makefile. Note that, you have to first create the COIN
  libraries Cgl, Clp, Osi, OsiClp and CoinUtils.

  2. Once configuration is done, open a command line terminal and type

  {{{nmake sym.mak}}}

  This will make the SYMPHONY library {{{libSymphony.lib}}} and the executable
  {{{symphony}}} in {{{Debug}}} directory. The library, together with the header
  files in {{{SYMPHONY\include\}}}, can then be used to call SYMPHONY from any
  C/C++ code. The API for calling SYMPHONY is described in the user's manual.

  3. To test the executable, type

  {{{symphony.exe -F ..\..\SYMPHONY\Datasets\sample.mps}}}

  in the output directory. If you want to use the interactive optimizer, simply
  type

  {{{symphony.exe}}}

  and then type {{{help}}} or {{{?}}} to see a list of available commands.