source: trunk/INSTALL @ 18

Last change on this file since 18 was 18, checked in by pbelotti, 11 years ago

minor changes

File size: 5.0 KB
Line 
1###############################################################
2#                                                             #
3#                        Couenne                              #
4#                                                             #
5#  (Convex Over and Under ENvelopes for Nonlinear Estimation) #
6#                                                             #
7###############################################################
8
9
10### Downloading Couenne ######################################
11
12Couenne is found in the COIN-OR repository. It can be downloaded with
13Subversion (http://subversion.tigris.org). Run the following command
14(if you are reading this file, you probably have Couenne already and
15don't need to):
16
17$ svn co https://projects.coin-or.org/svn/Couenne/trunk Couenne
18
19This creates a directory Couenne/ and downloads most of the necessary
20source files that are needed for building Couenne.
21
22
23### Obtaining Third Party code ###############################
24
25Couenne also requires that some third party packages, i.e. software
26that is not found on the COIN-OR repository, be downloaded and
27installed by the user (unless they are already on his/her
28machine). These are ASL, Blas, Lapack, and HSL. For the first three,
29simply move to the corresponding directory and run the get.XYZ script
30file. For instance, ASL can be downloaded as follows:
31
32$ cd ThirdParty/ASL
33$ ./get.ASL
34$ cd ../..
35
36and similarly for Blas and Lapack. To download HSL, see the
37instructions in ThirdParty/HSL/INSTALL.HSL to obtain two files that
38are necessary to Ipopt.
39
40
41### Building Couenne #########################################
42
43To build Couenne, you may just run the commands "configure" and "make".
44However, it is usually desirable to have several builds in separate
45sub-directories.  To do so, create a subdirectory and run configure
46and make from there:
47
48$ mkdir build
49$ cd build
50$ ../configure -C
51$ make
52
53The libraries and executables will by default be installed in
54subdirectories of the directory where you have run the configure/make
55scripts. However, by properly setting the configure option --prefix,
56you can install Couenne in a different directory:
57
58$ ../configure --prefix=/usr/local
59
60This installs executables in /usr/local/bin and libraries in
61/usr/local/lib.  You may have to run the "make install" command
62as a super user.
63
64
65
66### Testing ####################################################
67
68There are a few built-in tests to check whether Couenne is installed
69properly and that it solves certain MINLPs correctly.  Before running
70"make install", you may run
71
72$ make unitTest
73
74to test most features of Couenne (reliability branching, bound
75tightening, etc).  The test may take a few minutes as several MINLP
76problems are solved in the process, each resulting in a short output
77line:
78
79$ make unitTest
80
81Testing couenne.opt.vt
82Global Optimum Test on circle.nl                                OK
83Global Optimum Test on cube.nl                                  OK
84
85...
86
87Global Optimum Test on qquad.nl                                 OK
88Global Optimum Test on sin.nl                                   OK
89Global Optimum Test on small2.nl                                OK
90Global Optimum Test on toy.nl                                   OK
91
92$
93
94If all these tests return OK, congratulations! You have set up Couenne
95correctly.  It is now safe to install Couenne.
96
97
98### Installing and using Couenne ###############################
99
100Simply run
101
102$ make install
103
104to install header files, libraries, and executables as specified by
105the --prefix option given at the configure command. For instance, if
106option "--prefix=/usr/local/" was given, now the couenne executable is
107found in /usr/local/bin/couenne and you may invoke it simply by
108
109$ couenne stub.nl
110
111(assuming /usr/local/bin is included in your $PATH environent
112variable). If no such option was used, the executable of Couenne is
113found in the bin/ directory. In this case, simply run
114
115$ bin/couenne stub.nl
116
117Where stub.nl is a nonlinear programming problem file created with
118AMPL. Stub files can be generated from AMPL as follows: consider a
119model file xyz.mod and a data file xyz.dat. Run the following AMPL
120commands:
121
122$ ampl
123ampl: model xyz.mod
124ampl: data xyz.dat
125ampl: write gxyz;
126ampl: quit;
127
128This will create a stub file xyz.nl that can be fed to Couenne (notice
129the "g" after the "write" keyword).
130
131Couenne can be fine-tuned by setting parameters in the option file couenne.opt,
132which is read from the same directory where Couenne is launched. A typical
133couenne.opt is provided in Couenne/src/, with some explanation on how to use
134its parameters. You may copy it to your directory and change some of the parameters,
135however those set by default are usually best on most of the instances we have tried.
136
137
138### Documentation ##############################################
139
140Doxygen documentation can be generated by running
141
142$ make doxydoc
143
144from the same build/ directory where you ran configure, make, and make
145install. Documentation in both html and LaTeX format can be found in
146the Doc/ subdirectory. Fire up your browser and take a look at
147Doc/html/index.html for documentation of Couenne.
Note: See TracBrowser for help on using the repository browser.