###############################################################
#                                                             #
#                        Couenne                              #
#                                                             #
#  (Convex Over and Under ENvelopes for Nonlinear Estimation) #
#                                                             #
###############################################################


### Downloading Couenne ######################################

Couenne is found in the COIN-OR repository. It can be downloaded with
Subversion (http://subversion.tigris.org). Run the following command
(if you are reading this file, you probably have Couenne already and
don't need to):

$ svn co https://projects.coin-or.org/svn/Couenne/stable/0.2 Couenne

This creates a directory Couenne/ and downloads most of the necessary
source files that are needed for building Couenne.


### Obtaining Third Party code ###############################

Couenne also requires that some third party packages, i.e. software
that is not found on the COIN-OR repository, be downloaded and
installed by the user (unless they are already on his/her
machine). These are ASL, Blas, Lapack, and one of the two packages 
HSL or MUMPS. For the first three, simply move to the corresponding 
directory and run the get.XYZ script file. For instance, ASL can be 
downloaded as follows:

$ cd ThirdParty/ASL
$ ./get.ASL
$ cd ../..

and similarly for Blas and Lapack. To download HSL, see the
instructions in ThirdParty/HSL/INSTALL.HSL to obtain two files that
are necessary to Ipopt.


### Building Couenne #########################################

To build Couenne, you may just run the commands "configure" and "make".
However, it is usually desirable to have several builds in separate
sub-directories.  To do so, create a subdirectory and run configure
and make from there:

$ mkdir build
$ cd build
$ ../configure -C
$ make

The libraries and executables will by default be installed in
subdirectories of the directory where you have run the configure/make
scripts. However, by properly setting the configure option --prefix,
you can install Couenne in a different directory:

$ ../configure --prefix=/usr/local

This installs executables in /usr/local/bin and libraries in
/usr/local/lib.  You may have to run the "make install" command 
as a super user.



### Testing ####################################################

There are a few built-in tests to check whether Couenne is installed
properly and that it solves certain MINLPs correctly.  Before running
"make install", you may run

$ make unitTest

to test most features of Couenne (reliability branching, bound
tightening, etc).  The test may take a few minutes as several MINLP
problems are solved in the process, each resulting in a short output
line:

$ make unitTest

Testing couenne.opt.vt
Global Optimum Test on circle.nl                                OK
Global Optimum Test on cube.nl                                  OK

...

Global Optimum Test on qquad.nl                                 OK
Global Optimum Test on sin.nl                                   OK
Global Optimum Test on small2.nl                                OK
Global Optimum Test on toy.nl                                   OK

$

If all these tests return OK, congratulations! You have set up Couenne
correctly.  It is now safe to install Couenne.


### Installing and using Couenne ###############################

Simply run

$ make install

to install header files, libraries, and executables as specified by
the --prefix option given at the configure command. For instance, if
option "--prefix=/usr/local/" was given, now the couenne executable is
found in /usr/local/bin/couenne and you may invoke it simply by

$ couenne stub.nl

(assuming /usr/local/bin is included in your $PATH environent
variable). If no such option was used, the executable of Couenne is
found in the bin/ directory. In this case, simply run

$ bin/couenne stub.nl

Where stub.nl is a nonlinear programming problem file created with
AMPL. Stub files can be generated from AMPL as follows: consider a
model file xyz.mod and a data file xyz.dat. Run the following AMPL
commands:

$ ampl
ampl: model xyz.mod
ampl: data xyz.dat
ampl: write gxyz;
ampl: quit;

This will create a stub file xyz.nl that can be fed to Couenne (notice
the "g" after the "write" keyword).

Couenne can be fine-tuned by setting parameters in the option file couenne.opt, 
which is read from the same directory where Couenne is launched. A typical 
couenne.opt is provided in Couenne/src/, with some explanation on how to use 
its parameters. You may copy it to your directory and change some of the parameters,
however those set by default are usually best on most of the instances we have tried.


### Documentation ##############################################

Doxygen documentation can be generated by running

$ make doxydoc

from the same build/ directory where you ran configure, make, and make
install. Documentation in both html and LaTeX format can be found in
the Doc/ subdirectory. Fire up your browser and take a look at
Doc/html/index.html for documentation of Couenne.