-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
executable file
·243 lines (198 loc) · 10.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
Welcome to OBOE.
NAME
OBOE - Oracle Based Optimization Engine.
A package for solving general convex non-differentiable optimization
problems.
SYNOPSIS
This directory contains the code and documentation for OBOE package.
The package is designed to solve convex optimization problems of the
following form:
min f1(y) + f2(y)
subject to y in Y1 and Y2
where f1 and f2 are convex functions on R^n and Y1, Y2 are subsets of R^n.
The function f1 and the set Y1 is revealed by a first order oracle. f2
is a convex twice continuous differentiable function, Y2 is a 0-level
set of a convex twice continuous differentiable function g(y).
In the current implementation we restrict Y2 to be R^n or specified by a
set of linear constraints given by g(y) <= 0.
Additionally, the variables y can be constrained to lie in an affine
set {y | D^Ty = d}.
Such optimization problems typically occur as a result of solving the
dual of some other optimization problem. In particular the Lagrangian
relaxation schemes provide the problems described in the format above.
LICENSE
OBOE is developed at University of Geneva. Please see the file COPYING for
details.
OBTAINING OBOE
In this package we provide the C++ implementation of OBOE. There exists
a MATLAB version, which is a precursor to this distribution.
For obtaining OBOE for C++ or MATLAB please contact
Jean-Philippe Vial <[email protected]>
DOCUMENTATION
For documentation, please see the files in the doc subdirectory.
OBOE-UserGuide.pdf in doc/userguide provides a comprehensive
documentation on the theory and usage of OBOE.
The code is documented using the doxygen tool which can be retrieved by
opening doc/html/index.html in a browser.
GETTING STARTED
For building and installation instructions please see the INSTALL file.
In addition OBOE uses the following external libraries:
1. BLAS Basic Linear Algebra Subprograms
http://www.netlib.org/blas
2. LAPACK Package for solving system of linear equations.
http://www.netlib.org/lapack
3. LAPACK++ or lapackpp: A C++ library for BLAS/LAPACK based linear
algebra computaions.
For more information on LAPACK++ we refer
http://www.sourceforge.net/projects/lapackpp
Download page:
http://sourceforge.net/project/showfiles.php?group_id=99696
4. OBOE can optionally be configured to use LP solver library glpk. The
use of this library enables the user to verify whether the
localization set has non-empty interior.
If the user chooses to use glpk, they need to run configure with the
following option:
configure --with-glpk=yes
In addition, they also need to specify the glpk directory by setting
the environment variable GLPK_DIR. OBOE assumes this directory has the
glpk library and include files in the lib and include directories
respectively.
5. Boost libraries for serialization. To serialize the OBOE data
structures OBOE can optionally be configured to enable serialization.
In order to do this the user needs to run configure with the following
option:
configure --enable-serialization=yes
This assumes that the boost libraries for serialization are present.
BLAS and LAPACK:
OBOE by default tries to link to the standard blas/lapack libs typically
found in /usr/lib. One can override this behaviour by setting the
environment variable BLAS, before doing configure and compiling the code.
Similarly the lapack library can be specified by setting the environment
variable LAPACK.
We recommend using the fine tuned blas and lapack libraries provided by
ATLAS (http://math-atlas.sourceforge.net/).
In the following notes <OBOE_DIR> should be replaced with the absolute
path to the directory where OBOE is installed.
For Linux Pentium machines one can use the libraries provided in extras.
You can set BLAS to <OBOE_DIR>/extras/LinuxP4SSE2/libatlas.so and
LAPACK to <OBOE_DIR>/extras/LinuxP4SSE2/lapack.so.
(Depending on your environment you might also have to include path to
these libraries in the environment variable LD_LIBRARY_PATH if you get
error loading libraries at runtime. In this case you just need to append
the LD_LIBRARY_PATH with a command ike:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<OBOE_DIR>/extras/LinuxP4SSE2.
For other platforms it is best to get the blas and lapack libraries from
ATLAS.
LAPACK++:
The environment variable for LAPACK++ are LAPACKCPP_DIR and
LAPACKCPP_LIB.
OBOE assumes that the headers for LAPACK++ are in LAPACKCPP_DIR/include
and library is given by LAPACKCPP_LIB.
SERIALIZATION:
To enable support for serialization of OBOE structures, we use the
serialization libraries provided by boost
http://www.rrsd.com/boost/libs/serialization/doc/index.html
By default the support for these libraries is turned off, but can be
enabled by
configure --enable-serialization=yes
These libraries enable the save and load facilty for OBOE, incase the
user wants to save the state and restart OBOE.
COMPILING and INSTALLATION:
The installation of OBOE uses the standard autoconf/automake utilities.
Once the above environment variables have been setup, the user can just
type configure followed by make to compile the code which resides in src.
The installation assumes that LAPACK++ libraries have already been built.
QUICK START:
We give the few steps for a quick installation of OBOE:
1. Set the following environment variables
BLAS
LAPACK
LAPACKCPP_DIR
LAPACKCPP_LIB
(If the libraries are shared objects(.so) then ensure that they can be
located at runtime by providing the directories in the LD_LIBRARY_PATH
environment variable.
2. configure --prefix=<path to directory where OBOE libraries should be installed>
(For users not familiar with configure, configure --help will let you
know what options are available)
For the following examples we are assuming that the user chooses to install
OBOE in their current directory, <OBOE_DIR> which is the default install directory for OBOE.
3. make install
This will create a bunch of libraries for OBOE.
The makefiles used by OBOE for creating the application code in
src/Benchmark/QP, for example, can eaily be modified by the user
to plug-in their own application code. They need to modify the Makefile.am
and run make check.
If the user wants to use their own build environmemt, they need to ensure
that the application code links with the OBOE libraries by providing the
following option at compile time
<compile_cmd> -I<OBOE_DIR>/include -L<OBOE_DIR>/lib <OBOE_DIR>/lib/libaccpm.a <OBOE_DIR>/lib/libaccpmcore.a <OBOE_DIR>/lib/libaccpmparam.a <OBOE_DIR>/lib/libaccpmoracle.a <OBOE_DIR>/lib/libaccpmla.a
To create a single OBOE library instead of the 5 above the users can use
the script create_oboe_lib.sh.
(This script assumes bash shell, but the users can do something similar
on other shells.)
This will create a liboboe.a which can be linked in as follows:
<compile_cmd> -I<OBOE_DIR>/include -L<OBOE_DIR>/lib <OBOE_DIR>/lib/liboboe.a
Note: In addtion the user will have to link in libg2c, BLAS, LAPACK,
LAPACK++ libraries. If configured to use the glpk librairies in a similar
manner, by appending the -I include FLAG and -L link flag.
(These are provided as the OBOE_INCLUDES and OBOE_LDFLAGS and OBOE_LDADD
variables via the configure command to the final Makefiles.)
To see more details look at one of the application code in
<OBOE_DIR>/src/Benchmark.
EXAMPLES
Since OBOE is provided as a C++ callable library, the users need to write
their driver programs, specifying the Oracle for their application.
As a guide we provide a few example applications in src/Benchmark.
Refer to src/Benchmark/README for the example applications solved
using OBOE.
To create application executable for the tests provided in the release:
cd src/Benchmark/<application>
make check
The application code, which resides in directory src/Benchmark, creates
binaries for each application.
The binaries have the form oboe<application name> and can be created by
the command make check.
PARAMETERS
The parameters for configuring OBOE are described in
src/ProblemInput/param.oboe
The Parameters object used for OBOE applications read in file in the
above format. The user can create their own parameter file and specify
their options.
WINDOWS
For extra instructions regarding installation on windows, read README.W32
for using mingw environment for compiling.
For Visual Studio .NET projects refer to directory WIN32.
The include files are same as for the non-windows version i.e. in
<OBOE-DIR>/include directory.
There library, lib/OBOE.vs5.lib is built wth Visual Studio .NET 2005,
and can be used directly for users with compatible build environment
otherwise they need to build their own.
CONTENTS
The OBOE distribution has the following top-level directory structure.
config/
Helper files for configuring OBOE. This is part of the GNU Autoconf
system and is of no interest to most users.
doc/
Documentation for the distribution. Point a browser at
doc/html/index.html to see the available documentation.
extras/
Some pre-built libraries for building on Linux and windows
platforms. These are provided without guarantee and it is probably
best to get the appropraite BLAS and LAPACK libraries on your own.
include/
The header files are copied from src/ into this directory as part of
the installation process.
src/
Source files for OBOE distribution.
CREDITS
OBOE has been developed at Logilab, HEC, Universite de Geneve.
The work has benefitted from the research and experience and many
researchers who worked at Logilab in the past years.
The current version is maintained by:
Nidhi Sawhney
Jean-Philippe Vial
HEC, Universite de Geneve
Jean-Philippe Vial <[email protected]>