%===========================================================================%
%                                                                           %
% This file is part of the documentation for the SYMPHONY MILP Solver.      %
%                                                                           %
% SYMPHONY was jointly developed by Ted Ralphs (ted@lehigh.edu) and         %
% Laci Ladanyi (ladanyi@us.ibm.com).                                        %
%                                                                           %
% (c) Copyright 2000-2015 Ted Ralphs. All Rights Reserved.                  %
%                                                                           %
% SYMPHONY is licensed under the Eclipse Public License. Please see         %
% accompanying file for terms.                                              %
%                                                                           %
%===========================================================================%

This chapter is concerned with detailed instructions for building and
installing SYMPHONY, along with its associated libraries and applications.
Note that the procedures outlined below may change over time, so please also
check the current README documentation for the COIN-OR Optimization suite at
\begin{center}
\url{https://coin-or.github.io/user_introduction.html}  
\end{center}

documentation of the \code{coinbrew} build script (referenced below) at
\begin{center}
\url{https://coin-or.github.io/coinbrew}.
\end{center}

\section{Installing the Binary Distribution}

For the users who only need to use SYMPHONY as a black-box solver solver or
only need the SYMPHONY callable library in order to develop a custom
application, there are binary distributions released for different compilers
and platforms. Each distribution consists of an executable and libraries built
from the source code of SYMPHONY version \VER. It is important to note,
however, that the pre-compiled binaries are missing some very useful
functionality because of the fact that we are unable to distribute code linked
to libraries licensed under the GNU General Public License (GPL). There are
also a number of other potentially useful configurations (such as the parallel
version) that we do not distribute in binary form. Building from source should
be easy in most environments and will give you more flexibility. See
Section~\ref{building_from_source} for more information on additional
functionality available when building from source.
 
Binaries for many platforms are available as assets attached to releases on
Github. For the current release, the URL is
\begin{center}
\url{https://github.com/coin-or/SYMPHONY/releases/tag/releases\%2F\VER}  
\end{center}
In many cases, however, binaries can be installed more easily with a package
manager. 
\begin{itemize}
\item \textbf{Linux}: On Debian/Ubuntu, SYMPHONY is available in the package \code{coinor-symphony} and can be installed with apt. On Fedora, SYMPHONY is available in the package \code{coin-or-SYMPHONY}.
\item \textbf{Mac OS X}: The easiest way to get SYMPHONY on Mac OS X is
  through Homebrew (\url{https://brew.sh}).
  \begin{itemize}
    \item \code{brew tap coin-or-tools/coinor}
    \item \code{brew install coin-or-tools/coinor/symphony}
  \end{itemize}
\end{itemize}

\subsection{Installation in Unix-like environments}
\label{building-unix}

The installation consists of unpacking the distribution into an appropriate
installation directory, such as \code{/usr/local/symphony}.
%\begin{itemize}
%\item
Unpack the distribution with
{\color{brown}
\begin{verbatim}
 tar xzvf SYMPHONY-releases.\VER-XXX.tgz
\end{verbatim}
}
where \code{XXX} indicates the platform and the version of compiler used to
build the distribution. Switch into the root directory of the unpacked
distribution. 

%\item
Test the executable by going to the \code{bin} directory and typing 
{\color{brown}
\begin{verbatim}
 ./symphony
\end{verbatim}
}
This will start up the solver in interactive mode. Type \code{help}
or \code{?} to see a list of available commands or see Chapter
\ref{API-overview} for instructions on using the interactive solver.

%\item
To test the callable library, the distribution
includes sample files in \code{examples} directory:  \\ \\
\code{milp.c}: This sample code is an implementation of a basic MILP
solver using SYMPHONY's C callable functions with user defined input (see
Section \ref{callable_library}). To test the code, go to the
\code{examples} directory and type 
{\color{brown}
\begin{verbatim}
 make milp 
 milp
\end{verbatim}
}
You may need to customize some paths in the Makefile and to set the
environment variable \code{LD\_LIBRARY\_PATH}. 
\code{milpOsi.c}: This sample code is an implementation of a basic MILP 
solver using SYMPHONY's C++ callable functions (through OsiSym interface)
with user defined input (see Section \ref{OSI}). To test the code, 
go to \code{examples} directory and type, 
{\color{brown}
\begin{verbatim}
 make milpOsi
 milpOsi
\end{verbatim}
}
%\end{itemize}

If everything is working properly, the libraries, executables and header files
can be installed in appropriate system directories if desired. This must be
done by hand. This step will be done automatically if building from source
using the automatic scripts provided (see below). It is important to note,
though, that 


\subsection{Installation for Use With Microsoft Visual C++}

Download and unpack the archive \code{SYMPHONY-releases.\VER-XXX.zip} in an
appropriate installation directory, such as \code{C:\bs Program Files (x86)\bs
  SYMPHONY}. 

Test the executable by opening Windows Explorer and double-click
on \code{symphony.exe} in the \code{bin}
directory in the folder in which the distribution was unpacked. This should
open a Window in which the interactive solver will appear. Type \code{help}
or \code{?} to see a list of available commands or see Chapter
\ref{API-overview} for instructions on using the interactive solver.

To test the callable library, the distribution includes sample codes
along with associated project files in the \code{examples} directory. \\ \\
\code{milp.c}: This sample code is an implementation of a basic MILP
solver using SYMPHONY's C callable functions with user defined input (see
Section \ref{callable_library}). To build and test the code, open the SYMPHONY
MSVC++ solution file and build the project \code{milp}, as
described below in the next section.

% Applications????

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Building From Source} 
\label{building_from_source}

SYMPHONY uses the COIN-OR build system and the GNU autotools to automate the
build process. The build process should therefore be similar in all
Unix-like environments. It is even possible to use this system to build SYMPHONY
in Windows using the Microsoft Visual C++ compiler if you have MSys2
(\url{https://msys2.github.io/}), CYGWIN (\url{http://cygwin.org/}), or the
Windows Subsystem for Linux
(\url{https://docs.microsoft.com/en-us/windows/wsl/install-win10}) installed.
The instructions below 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 a C or C++ code 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 behavior. For information on customizing SYMPHONY using callbacks, a
quick start guide is provided below. More detailed information is provided in
Chapter~\ref{SYMPHONY-development}.

\subsection{External Dependencies}

\subsubsection{The LP Engine} SYMPHONY requires the use of a third-party
  callable library to solve the LP relaxations once they are formulated. The
LP solver is called through Open Solver Interface, also available from
\htmladdnormallink{COIN-OR}{https://github.com/coin-or/Osi}.
The list of solvers with OSI interfaces currently numbers eight and includes
both commercial and open source alternatives. By default, SYMPHONY now uses
the COIN LP solver (Clp). However, if another LP solver is desired, this is
possible by changing the configuration settings.

\subsubsection{GMPL Parser} If you would like to be able to parse GMPL models
(GMPL is a subset of AMPL), you will need to install GLPK
(\url{http://www.gnu.org/software/glpk/}). To do so automatically, run the
\texttt{get.Glpk} script in the \texttt{ThirdParty/Glpk} directory. After
that, run configure with the additional argument \texttt{--with-gmpl} and Glpk 
will be built and linked automatically, enabling the ability to read GMPL 
files.

\subsubsection{COIN Libraries} SYMPHONY uses other COIN libraries for certain
functionality, such as parsing MPS files, solving linear programs, generating
valid inequalities, and for general matrix utilities. The libraries required
for this functionality are now included with the distribution.

\subsubsection{GNU Libraries} If the \code{readline} and \code{history} libraries
are available, the interactive solver will have command history and command
completion available. This functionality is only available in Unix-like
environments by configuring with the \code{--enable-gnu-packages} option (see
below).

\subsection{Building in Unix-like environments}
\label{getting_started_unix}

\subsubsection{Building the Standard Configuration}

\paragraph{Building on Linux.}

Most Linux distributions come with all the required tools installed, but to be
sure, check that you have
\begin{itemize}
  \item pkg-config, wget, gcc, g++, make, git, tar
  \item BLAS and LAPACK
  \item Optional additions
    \begin{itemize}
    \item Metis
    \item Suitesparse
    \item libamd
    \item Cholmod
    \item Nauty
    \end{itemize}
\end{itemize}

To obtain the source code, the first step is to get the installer that will
then fetch the source for SYMPHONY and all its dependencies. *You do not need
to clone SYMPHONY first, just do the following!* Open a terminal and execute

{\color{brown}
\begin{verbatim}
git clone https://www.github.com/coin-or/coinbrew
\end{verbatim}
}

Next, to check out source code for and build all the necessary projects
(including dependencies), use the \code{coinbrew} script.

{\color{brown}
\begin{verbatim}
cd coinbrew
chmod u+x coinbrew
./coinbrew
\end{verbatim}
}

(Note: The \code{chmod} command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. The
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER
\end{verbatim}
}

The \code{coinbrew} script invokes a separate \code{configure} script that is
auto-generated using the GNU autotools. This script takes a wide range of
additional options and these options can be specified on the commnd-line when
running \code{coinbrew}. For example, to build with debugging symbols,
do

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --enable-debug
\end{verbatim}
}

To get help with additional options available in running the script, do

{\color{brown}
\begin{verbatim}
./coinbrew --help
\end{verbatim}
}

The above procedures will build all required dependencies and SYMPHONY itself.
Afterwards, the binaries will be installed in the directory
\code{dist/bin} 
and the libraries in the directory \code{dist/lib}. If you wish to install in
a different directory, such as \code{/usr/local}, then run the command

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --prefix=/path/to/install/dir
\end{verbatim}
}

After installation, you will also need to add \code{/path/to/install/dir/bin} to your
\code{PATH} variable in your \code{.bashrc} and also add \code{/path/to/install/dir/lib}
to your \code{LD\_LIBRARY\_PATH} if you want to link to COIN libraries. 

\paragraph{Building on Windows.}

By far, the easiest way to build on Windows is with the GNU autotools and the
GCC compilers. The first step is to install either
\begin{itemize}
\item Msys2 (\url{https://msys2.github.io/})
\item Windows Subsystem for Linux (\url{https://docs.microsoft.com/en-us/windows/wsl/install-win10})
\end{itemize}
If you don't want to fool around with
WSL (which is a great option if you already know your way around Unix), it is
recommended to use MSys2, since it provides a minimal toolset that is easy to
install. To get MSys2, download the installer from
\url{https://msys2.github.io/}.

Following the above steps, you should have the \code{bash} command
(with Msys2, be sure to run \code{msys2\_shell.bat} 
or manually add \code{msys64\bs usr \bs bin}, \code{msys64\bs mingw32\bs bin},
and 
\code{msys64\bs mingw64\bs bin} to your Windows path).   

Once you have bash installed and in your \code{PATH}, open a Windows terminal and
type 

{\color{brown}
\begin{verbatim}
bash
pacman -S make wget tar patch dos2unix diffutils git svn pkg-config zip unzip
\end{verbatim}
}

To obtain the source code, the first step is to get the installer that will then
fetch the source for SYMPHONY and all its dependencies. *You do not need to
clone SYMPHONY first, just do the following!* Open a terminal and execute

{\color{brown}
\begin{verbatim}
git clone https://www.github.com/coin-or/coinbrew
\end{verbatim}
}

Next, to check out source code for and build all the necessary projects
(including dependencies), execute the script in the \code{coinbrew}
subdirectory. To execute the script, do

{\color{brown}
\begin{verbatim}
cd coinbrew
chmod u+x coinbrew
./coinbrew
\end{verbatim}
}

(Note: The \code{chmod} command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. the
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER
\end{verbatim}
}
The \code{coinbrew} script invokes a separate \code{configure} script that is
auto-generated using the GNU autotools. This script takes a wide range of
additional options and these options can be specified on the commnd-line when
running \code{coinbrew}. For example, to build with debugging symbols,
do

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --enable-debug
\end{verbatim}
}

To get help with additional options available in running the script, do

{\color{brown}
\begin{verbatim}
./coinbrew --help
\end{verbatim}
}

To use the resulting binaries and/or libraries, you will need to add the
full path of the directory \code{build\bs bin} to your Windows executable
search \code{PATH}, or, alternatively, copy the conents of the build directory to 
\code{C:\bs Program Files (x86)\bs SYMPHONY} and add the directory \code{C:\bs
  Program Files (x86)\bs SYMPHONY\bs bin} 
to your Windows executable search \code{PATH}. You may also consider adding
\code{C:\bs Program Files (x86)\bs SYMPHONY\bs lib} to the \code{LIB} path and 
\code{C:\bs Program Files (x86)\bs SYMPHONY\bs include} to the \code{INCLUDE} path. 

It is possible to use almost the exact same commands to build with the Visual
Studio compilers. Before doing any of the above commands in the Windows
terminal, first run the \code{vcvarsall.bat} script for your version of Visual
Studio. Then follow all the steps above, but add \code{--enable-msvc} to the
\code{coinbrew} command.

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --enable-msvc
\end{verbatim}
}

\paragraph{Building on OS X.}

OS X is a Unix-based OS and ships with many of the basic components needed to
build COIN-OR, but it's missing some things. For examples, the latest versions
of OS X come with the \code{clang} compiler but no Fortran compiler. You may also
be missing the \code{wget} utility and \code{subversion} and \code{git} clients (needed for
obtaining source code). The easiest way to get these missing utilitites is to
install Homebrew (see http://brew.sh). After installation, open a terminal and
do

{\color{brown}
\begin{verbatim}
brew install gcc wget svn git
\end{verbatim}
}

To obtain the source code, the first step is to get the installer that will then
fetch the source for SYMPHONY and all its dependencies. *You do not need to
clone SYMPHONY first, just do the following!* Open a terminal and execute

{\color{brown}
\begin{verbatim}
git clone https://www.github.com/coin-or/coinbrew
\end{verbatim}
}

Next, to check out source code for and build all the necessary projects
(including dependencies), execute the script in the \code{coinbrew}
subdirectory. To execute the script, do

{\color{brown}
\begin{verbatim}
cd COIN-OR-OptimizationSuite
chmod u+x coi.install.sh
./coin.install.sh
\end{verbatim}
}

(Note: The \code{chmod} command is only needed if the execute permission is not
automatically set by git on cloning). Once you run the script,
you will be prompted interactively to select a project to fetch and build. the
rest should happen automagically. Alternatively, the following command-line
incantation will execute the procedure non-interactively.

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER
\end{verbatim}
}

With this setup, \code{clang} will be used for compiling C++ by default. If
you want to use the \code{gcc} compiler provided by Homebrew, then replace the
\code{build} command above with

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER CC=gcc-* CXX=g++-*
\end{verbatim}
}
where \code{*} is the version number of \code{gcc}. 
The install script invokes a separate \code{configure} script that is
auto-generated using the GNU autotools. This script takes a wide range of
additional options and these options can be specified on the commnd-line when
running \code{coinbrew}. For example, to build with debugging symbols,
do

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --enable-debug
\end{verbatim}
}

To get help with additional options available in running the script, do

{\color{brown}
\begin{verbatim}
./coinbrew --help
\end{verbatim}
}

If you wish to install in a different directory, such as \code{/usr/local}, then run
the command

{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --prefix=/path/to/install/dir
\end{verbatim}
}

After installation, you will also need to add \code{/path/to/install/dir/bin} to your
\code{PATH} variable in your \code{.bashrc} and also add \code{/path/to/install/dir/lib}
to your \code{DYLD\_LIBRARY\_PATH} if you want to link to COIN libraries. 

\subsubsection{Advanced Configuration Options}

The \code{coin.install.sh} script supports many advnaced configuration
options. See Figure~\ref{conf_opts} for a list of some of the options the user
may want to set.  
 
\begin{figure}[htb]
\begin{tabular}{ll}
\hline
\texttt{--enable-debug} & compile all projects with debug options set \\
\texttt{--enable-debug-symphony} & compile only SYMPHONY project with debug options \\
\texttt{--enable-msvc} & Under MSys2, compile so that executables do
not depend on the CYGWIN DLL \\
\texttt{--enable-static} & build static libraries \\
\texttt{--enable-static-executable} &  create a complete static executable \\
\texttt{--enable-gnu-packages} & compile with GNU packages \\ 
& compile interactive optimizer with readline library \\
\hline
\texttt{--disable-cgl-cuts} & disable generic cut generation \\
\texttt{--enable-sensitivity-analysis} & compile in the sensitivity analysis features \\
\texttt{--enable-root-only} & process only the root node \\
\texttt{--enable-frac-branching} & compile in the fractional branching option \\
\texttt{--enable-tests}&  perform additional sanity checks (for debugging purposes) \\
\texttt{--enable-tm-tests }& perform more tests  \\
\texttt{--enable-trace-path}&  additional debugging options \\
\texttt{--enable-cut-check}& additional debugging options \\
\texttt{--enable-statistics}& additional statistics \\
\texttt{--enable-pseudo-costs}& enable some experimental pseudo-cost branching tools \\
\texttt{--enable-draw-graph} &  enable IGD graph drawing application \\
\hline
\texttt{ --with-XXX-incdir} &  specify the directory with the header files for the XXX package \\ 
&where XXX is one of LP solver packages: cplex, glpk, osl, soplex, \\ 
& xpress \\
\texttt{--with-XXX-lib} &  specify the flags to link with the library  
XXX package \\ 
&where XXX is one of LP solver packages: cplex, glpk, osl, soplex, \\ 
& xpress \\
\texttt{--with-lp-solver[=lpsolver]} &  specify the LP solver in small 
letters (default lpsolver=clp) \\
\texttt{--with-application} &  compile the application library \\
\hline
\texttt{--enable-openmp} &   compile in OpenMP features \\
\texttt{--with-pvm } &  compile in parallel architecture (assuming that pvm is \\ 
&installed and the variable PVM\_ROOT is defined.) \\
\texttt{--without-cg} &  compile without cut generator module \\
\texttt{--without-cp} &  compile without cut pool module \\
\texttt{--without-lp} &  compile without LP solver module \\
\texttt{--without-tm} &  compile without tree manager module
\end{tabular}
\caption{A list of useful configuration options \label{conf_opts}}
\end{figure}

In order to enable or disable an option, add the option as an argument to the
\code{coin.install.sh} script. For instance, running 
{\color{brown}
\begin{verbatim}
./coinbrew fetch build SYMPHONY@\VER --enable-debug
\end{verbatim}
}
will compile the source files with the debugging flag.

It is possible to use compilers other than the default (which is \code{g++}).
For example, to perform an automated build of SYMPHONY using the MSVC++
compiler \code{cl} with GNU autotools in the CYGWIN environment configure with
{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --enable-msvc
\end{verbatim}
}

To test out the optimizer manually. a
sample MPS file called \code{sample.mps} and a sample GMPL/AMPL file called
\code{sample.mod} together with its data file
\code{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
{\color{brown}
\begin{verbatim}
 bin/symphony -F SYMPHONY/Datasets/sample.mps
\end{verbatim}
} To solve the GMPL model, use the \code{-F} switch to specify the file name
and the \code{-D} for the data file name if the input is in GMPL/AMPL format,
i.e., type 
{\color{brown}
\begin{verbatim}
 bin/symphony -F SYMPHONY/Datasets/sample.mod -D SYMPHONY/Datasets/sample.dat
\end{verbatim}}
For more MPS data files for further testing, see the MIPLIB library in the
\code{Data/} subdirectory. To run the interactive optimizer, execute SYMPHONY
without any command-line arguments, i.e., type
{\color{brown}
\begin{verbatim}
  bin/symphony 
\end{verbatim}}
and then type \code{help} or \code{?} to see a list of available commands.
After the SYMPHONY library and the executable are compiled and tested, you
can type
{\color{brown}
\begin{verbatim}
 make clean 
\end{verbatim}}
if you want to save disk space. That's it! Now you are ready to use SYMPHONY
callable library or solve generic MILP problems through the executable.

\subsubsection{Building for parallel architectures}

\paragraph{Shared-memory architectures.}

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.,
{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --enable-openmp
\end{verbatim}
} 
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.

After configuring, follow the earlier instructions for building and testing.
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
{\color{brown}
\begin{verbatim}
 bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps
\end{verbatim}
}
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
{\color{brown}
\begin{verbatim}
 bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps
\end{verbatim}
}

\paragraph{Distributed-memory architectures}
\label{distributed-build}

%\paragraph{Installing PVM.}
\label{PVM}
To compile a distributed application, it is necessary that PVM be installed
either in the system path or in the directory pointed to by the environment
variable \code{PVM\_ROOT} (this can be your home directory if PVM is not
already installed on your network). To install PVM yourself, the current
version can be obtained at \texttt{
\htmladdnormallink{http://www.csm.ornl.gov/pvm/}
{http://www.csm.ornl.gov/pvm/}}. It should compile and install without
problems on most architectures. You will have to make a few modifications to
your \code{.cshrc} file, such as defining the \code{PVM\_ROOT} environment
variable, but this is all explained clearly in the PVM documentation. Note
that all executables (or at least a link to them) must reside in the
\code{\$PVM\_ROOT/bin/\$PVM\_ARCH} directory in order for parallel processes
to be spawned correctly. The environment variable \code{PVM\_ARCH} is set in
your \code{.cshrc} file and should contain a string representing the current
architecture type. To run a parallel application, you must first start up the
daemon on each of the machines you plan to use in the computation. How to do
this is also explained in the PVM documentation.

%\paragraph{Configuring.}

To configure for a parallel build with the default parallel configuration,
invoke the configuration script as follows:
{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --with-pvm
\end{verbatim}
} 
Note that there are a number of different parallel configurations (see
Chapter \ref{SYMPHONY-modules} for an overview of SYMPHONY's parallel
modules). The default configuration is to build two parallel modules, the
first consisting of the master, tree management, and cut management modules,
while the second consisting of the node processing, and cut generation
modules. To build in another configuration, there are four configure flags
that control which modules run as separate executables and which are called
directly in serial fashion. The variables are as follows:
\begin{description}
        \item[] \code{--with-cg}: If set, then the cut generator function will
        be called directly from the LP in serial fashion, instead of running
        as a separate executable. This is desirable if cut generation is quick
        and running it in parallel is not worth the price of the communication
        overhead.
        \item[] \code{--with-cp}: If set, then the cut pool(s) will be
        maintained as a data structure auxiliary to the tree manager.
        \item[] \code{--with-lp}: If set, then the LP functions will be called
        directly from the tree manager. When running the distributed version,
        this necessarily implies that there will only be one active subproblem
        at a time, and hence the code will essentially be running serially. In
        the shared-memory version, however, the tree manager will be threaded
        in order to execute subproblems in parallel.
        \item[] \code{--with-tm}: If set, then the tree will be managed
        directly from the master process. This is only recommended if a single
        executable is desired (i.e.~the three other variables are also set to
        true). A single executable is extremely useful for debugging purposes.
\end{description}
These variables can be set in virtually any combination, though some
don't really make much sense. Note that in a few user functions that
involve process communication, there will be different versions for
serial and parallel computation. This is accomplished through the use
of \code{\#ifdef} statements in the source code. This is well documented
in the function descriptions and the in the source files containing
the function stubs.

%\paragraph{Building.}

Once configured, follow the build instructions in Section \ref{building-unix}
to build the code. Note that this will also compile the sequential version.
Make sure there are links from your \code{\$PVM\_ROOT/bin/\$PVM\_ARCH}
subdirectory to each of the executables in your \code{bin/} directory, as
required by PVM. In order to keep track of the various possible
configurations, executable and their corresponding libraries are named as
follows. The name of each executable is \code{symphony}, along with a
combination of the (abbreviated) names of the modules that were combined to
produce that executable joined by underscores: \code{m} for the master module,
\code{tm} for the tree management module, \code{lp} for the node processing
module, \code{cg} for the cut generation module, and \code{cp} for the cut
management module. For instance, in the default distributed configuration, the
executables produced are \code{symphony\_m\_tm\_cp} and
\code{symphony\_lp\_cg}.

To test the parallel version, first start the PVM daemon by typing \code{pvm}
on the command line and then typing \code{quit}. As above, invoke SYMPHONY
using the sample MPS file called \code{sample.mps} included with the
distribution. To specify the file name, use the \code{-F} command-line option,
i.e., in the root directory, type
{\color{brown}
\begin{verbatim}
 bin/symphony_m_EXT -F SYMPHONY/Datasets/sample.mps 
\end{verbatim}
} 

where \code{EXT} is the extension to be added according to the chosen
configuration of the modules.

\subsubsection{Building SYMPHONY Applications}
\label{build_appl_unix}

There are a number of sample applications available as examples of how to do
customized development with SYMPHONY. These include customized solvers for the
matching problem, the set partitioning problem (simple and advanced versions),
the vehicle routing and traveling salesman problems, the mixed postman
problem, the multi-criteria knapsack problem, and the capacitated network
routing problem. These applications are contained in the
\code{SYMPHONY/Applications/} subdirectory in the distribution. There is also
a white paper that guides the user through the development of the MATCH solver
in the \code{SYMPHONY/Doc/} directory. For detailed instructions on developing
your own application with SYMPHONY, see Chapter \ref{SYMPHONY-development}.

In order to compile SYMPHONY's applications in Unix-like environments, you
must first compile a version of the callable library with hooks for the
callback functions.
{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --with-application
 make 
 make install
\end{verbatim}
} This will create the application library called \code{libSymAppl} to be used
while building custom applications. Note that that the generic sequential
library and executable will also be made and installed.

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

\subsection{Building Using Microsoft Visual C++}
\label{getting_started_windows}

Here is a sketch outline of how to compile SYMPHONY in MS Windows with the
MSVC++ compiler. These instructions will lead you through the steps required
to compile SYMPHONY as a generic MILP solver. Note that the Windows version
has some limitations. Detailed timing information is not currently provided.
Support is only provided for running in sequential mode at this time.

First, obtain the source code by downloading from
\url{https://www.coin-or.org/download/source/SYMPHONY/}. Unpack the archive to
create the directory \code{SYMPHONY-\VER}. You now have three options. You
can either build using the MSVC++ IDE, build on the command-line with MSVC++
compiler, or use the NMAKE utility.

\subsubsection{Building with the MSVC++ Graphical Interface}
\label{using_msvc}

These instructions are for MSVC++ Version 8. Instructions for other versions
should be similar.

\begin{itemize}

\item Go to \code{MSVisualStudio\bs v10} directory and open the solution file
\code{symphony.sln}. 

\item Note that there are a number of additional preprocessor definitions that
control the functionality of SYMPHONY. These definitions are described in
\code{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 \code{libSymphony} project together with 
the required libraries and paths. For instance, if you 
want to enable GMPL reader option, you need to
\begin{itemize}
  \item add the directory of the header files of GLPK to the include 
files path
  \item add \code{USE\_GLPMPL} to the defines
  \item add the GLPK library to the solution
\end{itemize}
\item Make sure that the project \code{symphony} is set as the startup project
by choosing \code{Set as Startup Project} from the \code{Project} menu after
selecting the \code{symphony} project in the Solution Explorer. Choose
\code{Build Solution} from the Build menu. This should successfully build
the SYMPHONY library and the corresponding executable.

\item To test the executable, go to the \code{Debug} tab and choose
\code{Start Without Debugging}. This should open a Window in which the
interactive solver will appear. Type \code{help} or \code{?} to see a list of
available commands or see Chapter \ref{API-overview} for instructions on using
the interactive solver.

\end{itemize}

Note that there is some functionality missing from the Windows version. Most
prominently, the timing functions do not work. In addition, the Windows
version will only run in sequential mode for a variety of reasons. However, it
should be relatively easy to get it running in parallel if you can get PVM
working under Windows. 

\subsubsection{Building in a Windows Terminal}
\label{using_msdev}

These instructions are for MSVC++ Version 10. Instructions for other versions
should be similar, though project files for earlier versions are not well
maintained. 

\begin{itemize}
\item Open a command terminal (choose \code{Run} on the Start menu and type
\code{cmd} in the dialogue box). Go to the \code{MSVisualStudio\bs v10}
directory and type 
{\color{brown}
\begin{verbatim}
 devenv symphony.sln /Build "Win32|Release"
\end{verbatim}
}This will create both the 32-bit release version of SYMPHONY, including the
library \code{libSymphony.lib} and the executable \code{symphony}. Of course,
other configurations are suported as well and binaries will be created
side-by-side in the appropriate directories according to platform and
configuration selected. The library, together with the header files in
\code{SYMPHONY\bs include\bs}, can then be used to call SYMPHONY from any
C/C++ code. The API for calling SYMPHONY is described in Section
\ref{callable_library}.

\item Test the executable by opening Windows Explorer and double-clicking
on \code{symphony.exe} in the
\code{Debug\bs} subdirectory. This should open a Window in
which the interactive solver will appear. Type \code{help} or \code{?} to see
a list of available commands or see Chapter
\ref{API-overview} for instructions on using the interactive solver.

\item If you modify the source code of SYMPHONY, type 
{\color{brown}
\begin{verbatim}
 devenv symphony.sln /Rebuild "Win32|Release"
\end{verbatim}
}
in order to clean and rebuild everything.
\end{itemize} 

\subsubsection{Building with the MSVC++ compiler in MSys2}

It is possible to perform at automated build of SYMPHONY using the MSVC++
compiler \code{cl} with GNU autotools in the MSys2 environment. To do so,
follow the instuctions for building in Unix-like environments (see Section
\ref{getting_started_unix}), except when configuring, use the command

{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --enable-msvc
\end{verbatim}}

\subsubsection{Building SYMPHONY Applications}
\label{build_appl_msvc}

As mentioned above, there are a number of sample applications available as
examples of how to do development with SYMPHONY. These include solvers for the
matching problem, the set partitioning problem (simple and advanced versions),
the vehicle routing and traveling salesman problems, the mixed postman
problem, multi-criteria knapsack problem and, capacitated network routing
problem. These applications are contained in the \code{SYMPHONY/Applications/}
subdirectory in the distribution. There is also a white paper that guides the
user through the development of the MATCH solver in the \code{SYMPHONY/Doc/}
directory. For instructions on developing your own application with SYMPHONY,
see Chapter \ref{SYMPHONY-development}.

In order to compile SYMPHONY's applications in the Microsoft Visual C++
environment, obtain the source code as described earlier. As before, you then
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 below
instructions are for MSVC++ Version 6, but building in other versions should
be similar. All of the following commands should be executed in the
\code{SYMPHONY-\VER\bs Applications\bs XXX\bs MSVisualStudio\bs v10} directory,
where \code{XXX} is the name of the application to be built.

\paragraph{Building With the MSVC++ Graphical Interface}

\begin{itemize}

\item Open the solution file \code{xxx.sln}.

\item The configuration steps are exactly the same as that described in
  Section \ref{using_msvc}. The only difference is that you are using the
  \code{xxx} project instead of the \code{symphony} project. Go through the
  same steps to configure.

\item Once you have the proper settings, choose \code{Build
xxx.exe} from the \code{Build} menu. This should successfully 
build the executable.

\item
To test the executable, right click on the \code{xxx} project, go to the
\code{Debug\bs} tab and set the program arguments to 
\code{-F ..\bs ..\bs sample.xxx}. Note that command-line switches are 
Unix-style.

\item
Now choose \code{Execute} from the build menu and you have a working branch
and bound solver. 

\end{itemize}

\paragraph{Building in a Windows Terminal}
\begin{itemize}
\item Open a command terminal (choose \code{Run} on the Start menu and type
\code{cmd} in the dialogue box) and type
{\color{brown}
\begin{verbatim}
 devenv xxx.sln /Build "Win32|Release"
\end{verbatim}
} 
where \code{xxx} is the name of the application. This will create the
release version of the application executable, as above. 

\item To test the executable, type 
{\color{brown}
\begin{verbatim}
 Debug\xxx.exe -F ..\..\sample.xxx
\end{verbatim}
}
\item If the source files for the application are modified, type 
{\color{brown}
\begin{verbatim}
 devenv user.sln /Rebuild "Win32|Release"
\end{verbatim}
}
in order to clean and rebuild everything.
\end{itemize} 

\paragraph{Building with the MSVC++ compiler in MSys2}

It is possible to build applications using an automated build of SYMPHONY
with the MSVC++ compiler \code{cl} using the GNU autotools in the MSys2
environment. To do so, follow the instuctions for building in Unix-like
environments (see Section \ref{getting_started_unix}), except when
configuring, use the command

{\color{brown}
\begin{verbatim}
 ./coinbrew fetch build SYMPHONY@\VER --enable-msvc
\end{verbatim}}

Afterwards, you can build the individual applications using the ``make''
command, as usual in a Unix-like environment except that thecompiler used will
be \code{cl}.
