SYMPHONY Version 2.8 README

Welcome to SYMPHONY. To use SYMPHONY, you must be a registered user.
If you are not a registered user, please visit SYMPHONY's registration
page at http://branchandcut.org/SYMPHONY/license.htm to receive an
official copy of the distribution. All users should be familiar with
and agree to the terms of the End User License Agreement that comes
with the distribution. The distribution is for academic research use
only. Commercial use is prohibited. All source code and documentation
is Copyright 2000 by Ted Ralphs. This README may be distributed
freely.

DOCUMENTATION

Full documentation comes with your distribution in the directory
SYMPHONY-2.8/Doc and can also be downloaded at
ftp://branchandcut.org/pub/reference/. There is a white paper
(SYMPHONY.pdf) describing the basics of SYMPHONY and a user's guide
(SYMPHONY-2.8-Manual.pdf), both of which should be read prior to
developing an application.

WHAT'S NEW

1. New search rules. There are new search rules available in the tree
manager. These rules enable better control of diving.
	
2. More accurate timing information. Reported timing information is
now more accurate.

3. Idle Time Reporting. Measures of processor idle time are now
reported in the run statistics.

4. More efficient cut pool management. Cuts are now optionally ranked
and purged according to a user-defined measure of quality. See the
description of user_check_cut().

5. Easier use of built-in branching functions. Built-in branching
functions can now be more easily called directly by the user if
desired. Previously, these functions required the passing of internal
data structures, making them difficult for the user to call directly.
See the functions branch_* in the file LP/lp_branch.c for usage.

6. Better control of strong branching. A new strong branching strategy
allows the user to specify that more strong branching candidates
should be used near the top of the tree where branching decisions are
more critical. See the description of the relevant parameters in the
user's manual.

CHANGES TO THE USER INTERFACE

There are some minor changes to the user interface in order to allow
the use of the new features. If you have code written for an older
version, you will have to make some very minor modifications before
compiling with version 2.8.


1. user\_start\_heurs() now
includes as an optional return value a user-calculated
estimate of the optimal upper bound. This estimate is used to
control diving. See the description of the new diving rules
for more information. Since this return value is optional, you
need only add the extra argument to your function definition to
upgrade to the 2.8 interface. No changes to your code are
required. 
	
2. user\_check\_cut() now
includes as an optional return value a user-defined assessment
of the current quality of the cut. Since this return value is
optional, you need only add the extra argument to your
function definition to upgrade to the 2.8 interface. No
changes to your code are required.
	
3. user\_select\_candidates() now passes in the value of the
current level in the tree in case the user wants to use this
information to make branching decisions. Again, the new
argument just needs to be added to the function definition. No
changes to your code are required.

NOTE ON INSTALLATION

Because SYMPHONY is inherently intended to be compiled and run on
multiple architectures and in multiple configurations, I have chosen
not to use the automatic configuration scripts provided by GNU. With
the make files provided, compilation for multiple architectures and
configurations can be done in a single directory without reconfiguring
or "cleaning". This is very convenient, but it means that there is
some hand configuring to do and you might need to know a little about
your computing environment in order to make SYMPHONY compile. For the
most part, this is limited to editing the make file and providing some
path names. Also, for this reason, you may have to live with some
complaints from the compiler because of missing function prototypes, etc.

Note that if you choose not to install PVM, you will need to edit the
make file and provide an environment variable which makes it possible
for "make" to determine the current architecture. This environment
variable also allows the path to the binaries for each architecture to
be set appropriately. This should all be done automatically if PVM is
installed correctly.

GETTING STARTED

1. Unpack the distribution with "tar -xzf SYMPHONY-2.8.tgz".

2. Edit the various path variables in Makefile (SYMPHONY-2.8/Makefile)
to match where you installed the source code and where the LP
libraries and header files reside for each architecture on your
network. Other architecture-dependent variables should also be set as
required.

COMPILING THE SEQUENTIAL VERSION

1. Type "make" in the SYMPHONY root directory. This will first make
the SYMPHONY library (sequential version). After this step is
completed, you are free to type "make clean" and/or delete the
directories $ROOT/obj.* and $ROOT/dep.* if you want to save disk
space. You should only have to remake the library if you change
something in SYMPHONY's internal files.

2. After making the libraries, SYMPHONY will compile the user code and 
then make the executable for the sample application, a vehicle routing
and traveling salesman problem solver. The name of the executable will
be "master_tm_lp_cg_cp", indicating that all modules are contained in
s single executable.

3. To test the sample program, you can get some problem files from
http://branchandcut.org/VRP/data/ or the TSPLIB
(http://www.iwr.uni-heidelberg.de/iwr/comopt/software/TSPLIB95/). The
file format is that specified for the TSPLIB. There is also one sample
file included with the distribution. Make sure the executable
directory is in your path and type "master_tm_lp_cg_cp -F sample.vrp
-N 5", where sample.vrp is the sample problem file. The -N argument
gives the number of routes, which must be specified in advance. TSP
instances can also be solved, but in this case, the number of routes
does not need to be specified.

COMPILING FOR SHARED MEMORY

1. Obtain an OpenMP compliant compiler, such as Omni (free from 
http://pdplab.trc.rwcp.or.jp/Omni/). Other options are listed at 
http://www.openmp.org.

2. Set the variable CC to the compiler name in the make file and
compile as above.

3. Voila, you have a shared memory parallel solver.

4. Note that if you have previously compiled the sequential version,
then you should first type "make clean_all", as this version uses the
same directories. With one thread allowed, it should run exactly the
same as the sequential version so there is no need to have both.

COMPILING FOR DISTRIBUTED NETWORKS

1. If you wish to compile a distributed version of the 
code, obtain and install PVM from http://www.ccs.ornl.gov/pvm/.
Installing it is self-explanatory.

2. In the Makefile, be sure to set the COMM_PROTOCOL to "PVM". Also,
change one or more of COMPILE_IN_TM, COMPILE_IN_LP, COMPILE_IN_CG, and
COMPILE_IN_CP, to FALSE, or you will end up with the sequential
version. Various combinations of these variables will give you
different configurations and different executables. See the manual for
more information on setting them. Also, be sure to set the path
variables in the make file appropriately so that make can find the PVM
library.

3. Type "make" in the SYMPHONY root directory to make the
distributed libraries. As in Step 1 of the sequential version, you may
type "make clean" after making the library. It should not have to
remade again unless you modify SYMPHONY's internal files.

4. After the libraries, all executables requested will be made.

5. Make sure there are links from your $PVM_ROOT/bin/$PVM_ARCH/
directory to each of the executables in your SYMPHONY User/bin.$REV
directory. This is required by PVM.

6. Start the PVM daemon by typing "pvm" on the command line and then
typing "quit".

7. To test the sample program, you can get some problem files from
http://branchandcut.org/VRP/data/ or the TSPLIB
(http://www.iwr.uni-heidelberg.de/iwr/comopt/software/TSPLIB95/). The
file format is that specified for the TSPLIB. There is also one sample
file included with the distribution. Make sure the executable
directory is in your path and type "master -F sample.vrp
-N 5", where sample.vrp is the sample problem file. The -N argument
gives the number of routes, which must be specified in advance. TSP
instances can also be solved, but in this case, the number of routes
does not need to be specified. The actual executable name may not be
"master" if COMPILE_IN_TM is set to TRUE.

8. That's it! Now you are ready to develop your own application. See
the white paper and user manual for help.

LIST SERVE

There is a list serve for SYMPHONY users. To subscribe, send a message
containing "subscribe symphony-users" to majordomo@branchandcut.org.

AUTHORS

SYMPHONY was jointly developed by Ted Ralphs (tkralphs@lehigh.edu) and
Laci Ladanyi (ladanyi@watson.ibm.com).

BUG REPORTS

Bug reports should be sent to symphony-bugs@branchandcut.org.