INSTALL

REQUIREMENTS:

The build process for CSDP uses make, so your system must have make
installed.  The GNU make works quite well, but CSDP has also been
built with other versions of make.  The make files are very simple.

In order to build CSDP, you will need an ANSI C compiler.  The GNU C
compiler gcc works quite well, but the code has also been compiled
with Intel's icc, IBM's xlc, Sun's cc, and many other compilers.

Although CSDP itself is written in C, the BLAS/LAPACK libraries used
by CSDP were originally written in Fortran.  Combining C and Fortran
is generally straight forward, but you may have to install a Fortran
compiler in order to get run time libraries needed by the Fortran code
in BLAS/LAPACK.  In particular, on Linux systems using gcc and gfortran
you will link CSDP with the -lgfortran library.

Use of the CSDP library and the solver and theta functions requires
the BLAS library and a few routines from the LAPACK library.  Using
BLAS and LAPACK routines that have been optimized for your computer is
critical to getting good performance from CSDP, since the code
typically spends nearly all of its time in these routines.  On the
same hardware, it's not uncommon to find that optimized BLAS and
LAPACK routines are an order of magnitude faster than unoptimized BLAS
and LAPACK routines.

The original authors of BLAS and LAPACK have provided "reference
implementations" that are freely available but not very well
optimized.  If your system has BLAS and LAPACK libraries in /usr/lib,
there's a good chance that these are the reference implementations.
Using them is an easy way to start, but you may well find that you
need faster routines to get acceptable performance.

Most hardware manufacturers have developed optimized BLAS/LAPACK 
libraries for their systems, such as Apple's veclib for G5 
systems, Intel's Math Kernel Library (MKL), AMD's Core Mathematical
Library (ACML), IBM's extended scientific subroutine library (ESSL),
and Sun's sunperf library.  These typically have restrictive licenses and
may be expensive to purchase, but can provide very good performance.

An open source library that I recommend for use with CSDP is OpenBLAS.
See

  http://www.openblas.net/

You will generally need to compile OpenBLAS from source rather than installing
a binary version that is not optimized for your system.

CSDP also includes a set of routines for interfacing CSDP to MATLAB
and Octave.  This interface is entirely optional- CSDP works fine
without it.  In order to use this interface, you will need MATLAB (6.5
or later) or Octave (2.9.5 or later.)  The README file in the matlab
directory contains instructions for installing the matlab interface
and testing it on a sample problem.

DOWNLOADING CSDP:

The most current version of CSDP can be obtained using subversion from
the COIN-OR web site.  To do this, first install the subversion tools,
then issue the command

  svn co https://projects.coin-or.org/svn/Csdp/trunk
 
Or use a GUI to access the repository.

Alternatively, you can download a .tar or .zip archive of the source code
for the most recent stable release of CSDP from the project web site.

INSTALLING CSDP:

The following instructions assume that you're using a Linux system
with gcc, gfortran, LAPACK, and BLAS installed.  The make files will
have to be altered for other systems, but the basic process of
building the software will be similar.

After you've downloaded the source code, unpack the tar archive if you
downloaded a .tar archive of CSDP, and then go into the csdp
directory.  You will find subdirectories, lib, solver, theta,
example, and doc.  These contain the CSDP library, the command line
solver, an example program that computes the Lovasz theta number of
a graph, and a small example program showing how to call CSDP.  There
are Makefiles within these subdirectories.

There are two lines in the top level Makefile that will likely need to
be edited:

1. CFLAGS.  The CFLAGS variable specifies command line arguments to the
C compiler.  The default value of CFLAGS is appropriate for 64 bit Linux
systems using the gcc compiler.  It is:

CFLAGS=-m64 -march=native -mtune=native -Ofast, -fopenmp -ansi -Wall -DBIT64
       -DUSEOPENMP -DSETNUMTHREADS -DUSESIGTERM -DUSEGETTIME -I../include

The flags -m64 through -fopenmp tell gcc to produce optimized 64 bit
multithreaded code using the OpenMP features.  The flags -ansi and -Wall
tell gcc to produce warnings for any code that vioates the ANSI C standard.
The -D... flags specify options within the code as described below.
The -I../include flag specifies the location of CSDP's .h files.

The -D flags that are recommended for CSDP on 64 bit Linux are

-DBIT64              Used on 64 bit systems
-DUSEOPENMP          Used to build a parallel threaded version of CSDP
-DSETNUMTHREADS      Use OpenMP to set the number of threads to use.
-DUSESIGTERM         Terminate CSDP nicely after SIGTERM or other signals
-DUSEGETTIME         Use ANSI C gettime() to get wall clock running time.

For Windows 64 bit systems using the mingw64 compiler, recommended CFLAGS
are:

CFLAGS=-m64 -march=native -mtune=native -Ofast, -fopenmp -ansi -Wall -DBIT64
       -DUSEOPENMP -DSETNUMTHREADS -DUSEGETTIME -I../include

The only difference here is that -DUSESIGTERM is left out because Windows
doesn't support Linux/unix signals.

There are some flags that may rarely be useful on other systems:

-DCAPSBLAS           if BLAS routine names are capitalized
-DCAPSLAPACK         if LAPACK routine names are capitalized
-DNOUNDERBLAS        if BLAS routine names have no underscore
-DNOUNDERLAPACK      if LAPACK routine names have no underscore
-DHIDDENSTRLEN       if Fortran string lengths are hidden arguments

2. LIBS.  The LIBS= line of the Makefile specifies the location of the
CSDP library and the BLAS and LAPACK libraries.  The distributed version
of the Makefile has values suitable for a 64 bit Linux system with BLAS
and LAPACK installed in the system library directories:

LIBS=-static -L../lib -lsdp -llapack -lblas -lm

-static               produce a statically linked executable
-L../lib -lsdp        libsdp.a is in the lib subdirectory
-llapack -lblas       LAPACK and BLAS libraries
-lm                   C standard math library

In many cases it will be necessary to add the Fortran run time library:

-lgfortran

The LIBS variable will also have to be edited if your LAPACK and BLAS libraries
are not in the standard location or have different names.

For example, on my system, the OpenBLAS library is located in
/opt/OpenBLAS/lib/libopenblas.a.  This OpenBLAS library contains both
LAPACK and BLAS routines, so I don't need to specify a spearate LAPACK
library.  Thus I use the flags:

LIBS=-static -L../lib -L/opt/OpenBLAS/lib -lopenblas -lm

Once you've set the LIBS and CFLAGS variables in the top level Makefile,
issue the command
 
> make
 
to build CSDP.  Make will go into the lib, solver, theta, and example
subdirectories and compile the C code.

If the build fails, it is important to start by identifying where the
build failed.  Failures in building the CSDP library are extremely
rare.  Most reported failures have occured in the solver and theta
directories.  The most common problem in practice is that one or more
of the required libraries (blas or lapack) is missing.  In that
case you must install the required library before continuing with the
installation of CSDP.  If the build fails for some other reason, feel 
free to contact the author for help- we're interested in learning about
problems on different systems.  

If for some reason the build fails, it's a good idea to remove all
of the binaries before modifying the make files and rebuilding.  To do
this, issue the command
 
> make clean
 
Once the build appears to be successful, you can test the code with
 
> make unitTest
 
This will run tests of the stand alone solver csdp and Lovasz theta
program theta.  Compare the .out files produced by the tests with the
corresponding .correct files.  The actual values will typically vary
because of small differences in floating point round-off, compiler
optimizations, and so on.  However, the optimal objective values
should match to at least six digits, the relative primal and dual
infeasibilities should be smaller than 1.0e-7, and all DIMACS errors
should be smaller than 5.0e-7.

If either of the tests fail, please contact the author.

Once you're satisfied with tests, you can become root and issue the
command

> make install

This will copy csdp, rand_graph, complement, theta, and graphtoprob
into the /usr/local/bin directory.  If you use the C shell, remember
to "rehash" so that the shell will know that these programs have been
added to the /usr/local/bin directory.

The matlab directory contains .m files that provide a matlab interface
to CSDP solver. To install these .m files they must be added to your
matlab path.  This requires use of the path(...) command in
matlab. See '>help path' for instructions on adding a new directory to
your matlab path (you can put the .m files in any directory you wish,
then add that directory to your matlab path).