INSTALL -- An installation guide for OOQP. This page is part of the OOQP documentation .
If you have all the prerequisite packages installed on your system (see the PREREQUISITES section below), then you may type
./configure
make
to build OOQP. If you wish to install the package in a more permanent location, you may then type
make install
Support for external packages such as Ampl, Matlab and PETSc is not built automatically. See the appropriate sections below for instructions on how to build interfaces to these packages.
If you intend to build and install OOQP under Microsoft Windows, read the README_Windows file before you read the remainder of the current file.
Before discussing the specifics of packages that are needed for OOQP to be built, we make some general comments about the use of environment variables and the configure script.
The configure script attempts to determine properties of your system and compilers automatically. Occasionally, it will be unable to resolve some aspect of your environment satisfactorily; for example, the locations of certain external packages. In these cases, the script will report an error. You will need to set certain environment variables (and possibly obtain some additional software) before re-running configure.
To take one important example, consider the BLAS library, which is required for a successful build. If configure cannot determine the location of the BLAS automatically, you will need to set the LIBBLAS environment variable to the location of the BLAS library on your system. For most shells, a script of the following form will suffice:
LIBBLAS=/some/directory/libblas.a
export LIBBLAS
(Of course, /some/directory/libblas.a should be replaced by an actual path to libblas.a.) For the csh shell, and its derivatives, the form of the command is as follows.
setenv LIBBLAS /some/directory/libblas.a
The use of spaces is significant in these examples - particularly the absence of spaces surrounding the = sign in the first example. If you are uncertain which shell you are using it is safe to simply try both these commands; one should work.
For libraries, the value of the environment variable does not need to be a file name, but may instead be the name of the library as you want it to appear on the link line. For example, the setting
LIBBLAS=-lsunperf
is appropriate on some systems. (In this particular case, however, configure will find the sunperf library automatically).
Once LIBBLAS and other variables of interest are set appropriately, one may run the configure script by going to the OOQP directory and typing the following:
./configure
This script will copy the values of the environment variables into appropriate locations, so you do not need to set these variables permanently (that is, there is no need to modify your .login or .profile). However, if you need to re-run configure (after fixing some error or after acquiring additional external packages), you will need to be sure all appropriate environment variables are set appropriately before calling the script. It may help to make a note of the appropriate values.
An alternative approach is to modify the files GNUmakefile and PetscMakefile by hand to set environment variables appropriately. However, these files are generated automatically by the configure script, so any changes you make will be lost next time you run this script.
The following packages need to be installed on your system before OOQP may be built.
OOQP is written in standard C++, using only constructs that modern compilers stably support. Any sufficiently recent C++ compiler should work with OOQP.
OOQP uses a number of routines from the BLAS and LAPACK FORTRAN 77 libraries. C++ code that calls these routines adheres to typical intra-language calling conventions that work for a number of compiler suites. We recommend that those users who do not have a FORTRAN 77 compiler, or are having difficulty compiling OOQP using their FORTRAN compiler obtain F2C (see the USING F2C section below.)
We remark that the GNU C++ and FORTRAN compilers build OOQP correctly.
You may compile OOQP under any operating system you wish, but the installing instructions in the current file require the use of UNIX-style system utilities. For instructions on how to build OOQP under Microsoft Windows, see the README_Windows file.
A utility to maintain groups of programs. GNU make is freely and widely available, yields predictable performance across a wide variety of platforms, and has a number of useful features absent in many vendor-provided versions of make.You almost certainly have a version of make installed, which may or may not be GNU make. To find out, type: make --version
If you get anything other than a message telling you that this is a version of GNU make, try gmake --version
and finally
gnumake --version
If none of these succeed, then GNU make probably is not installed on your system. You may obtain a copy at http://www.gnu.org. Although our makefiles are not too elaborate, we do use some features of GNU make.
The BLAS (Basic Linear Algebra Subproblems) is a collection of routines that perform common linear-algebra operations used in scientific computing. Because these operations are so fundamental, a great deal of effort has gone into ensuring that they are implemented correctly and efficiently on various architectures. The BLAS may already be installed on your machine. If not, you must obtain a version and install it.
A Fortran reference implementation of the BLAS may be found at http://www.netlib.org/blas/index.html, but it is preferable to use a machine-optimized library if one is available. For Linux users, one such version may be found at http://www.cs.utk.edu/~ghenry/distrib/. Information about obtaining optimized versions of the BLAS for other architectures may be found on the Netlib page http://www.netlib.org/blas/index.html
The configure script will first test whether your compiler suite can find the BLAS library in a standard system location. If unsuccessful, it will search for the file in the following location in the OOQP distribution:
extras/blas/libblas.a.
Therefore, one option is to move an appropriate libblas.a file manually to this location.
If the configure script fails to find a BLAS library in the locations above, you will need to set the LIBBLAS environment variable explicitly to point to it. See ENVIRONMENT VARIABLES AND configure for information on how to do so.
MA27 and MA57 are codes for solving sparse symmetric indefinite linear systems. To build the default general QP solver, you must have one of those two codes installed.
These codes are part of HSL (formerly the Harwell Subroutine Library), a collection of ISO Fortran codes for large scale scientific computation.
MA27 is the default solver used with OOQP. MA57 supersedes MA27, but MA57 has more restrictive licensing requirements. We find that the MA57 version of the OOQP solver outperforms the MA27 version in general, but performance of the MA27 version is also acceptable.
MA27 is available free for noncommercial use. Detailed conditions of use are given at the time of registration.
To obtain MA27, go to
http://hsl.rl.ac.uk/archive/hslarchive.html
and click on ``Registration Form'' and fill out the online form. In the box labelled ``Package(s) Required'', enter ``MA27''. In the box labelled ``Brief Description of Likely Applications'' type the phrase ``MA27 for use with OOQP'' (no quotes, one line, left justified, no extra lines, no extra comments). If you register for use with OOQP, then we will be able to be more helpful if you have trouble obtaining or building MA27 (we cannot offer such help to unregistered users.)
You will be mailed a user name and password that allows you to download MA27 source from the HSL Archive. You will need the double precision versions of the MA27, FD05, ID05 and ZA02 packages, which you should save to files named ma27.f, fd05.f id05.f and za02.f respectively. The FD05, ID05 and ZA02 packages are machine-dependent. Most users will want to download the default version of these packages (generic IEEE or generic Unix), but read the options carefully to see if a version specific to your hardware or OS is available. Contact the maintainers of the HSL archive if you cannot determine which version of these packages is appropriate to your system. We note that the default version of these packages is appropriate for users running Linux on Intel hardware.
Move the downloaded FORTRAN (.f) files to the
extras/MA27/
subdirectory of the OOQP distribution directory. From within this directory, type
./configure
make
to generate the file ``libMA27.a''.
The configure script will look for libMA27.a in this directory extras/MA27.
If MA27 is already installed on your system, of if you wish to install MA27 in a different location, you may need to set the LIBMA27 environment variable to point to this library. See ENVIRONMENT VARIABLES AND configure for information on how to do so.
The procedure for MA57 is similar, once you have obtained (and licensed) a copy of the MA57 source from the HSL2000 collection. See
http://www.cse.clrc.ac.uk/Activity/HSL
for details on obtaining MA57 and other HSL2000 codes. Once you have obtained MA27, unpack the files into
extras/MA57
and follow the procedure outlined above for MA27.
The command
make
will build several executables in the current directory along with libraries containing the OOQP development framework in lib/. It will also copy the OOQP header files into include/. See the README file for a description of the conventions used to name the executables. One of the executables created will be
qpgen-sparse-gondzio.exe
This is the default solver that takes QPS files as input and uses MA27 to solve linear systems. Use of this solver is described extensively in the OOQP User Guide (doc/ooqp-userguide.pdf).
Interfaces of the qpgen solver to external packages, such as Ampl and Matlab, and variants that use linear solvers other than MA27 (such as MA57) are not built by default. To build the MA57-based version of the qpgen solver, you first need to install MA57 and set the LIBMA57 environment variable appropriately. Then type make all-ma57
One of the executables created will be
qpgen-sparse-ma57-gondzio.exe
which has the same functionality as qpgen-sparse-gondzio.exe.
The libraries that are built by the ``make'' command and moved to lib/ will be similarly incomplete. They will include libraries for those versions of OOQP which we anticipate that users will wish to embed as subroutines in their own problems. Please refer to the OOQP User Guide for further information, and contact the developers if you need a library that is not currently supplied.
Users who wish to create a new QP solver customized to a particular problem structure, or perform similarly intense development with OOQP, may wish to work in the OOQP src/ directory rather that relying on the libraries generated by the default build. Instructions on working with the OOQP course can be found in the OOQP User Guide.
OOQP has interfaces to several external packages.
OOQP may be invoked to solve convex QPs from within the modeling language Ampl. To use the OOQP Ampl interface, you must install the Ampl solver library and library headers. The source for this library, and pre-built versions for some platforms, may be downloaded from the OOQP page http://www.cs.wisc.edu/~swright/ooqp . Alternatively, you may download the source for the official site http://www.ampl.com/cm/cs/what/ampl/hooking.html
Unpack the source or binary archive into extras/ampl/solvers. If the library isn't already built, compile the amplsolvers.a library as instructed in the documentation accompanying the source. Rerun the configure script in the OOQP distribution, and type.
make ooqp-ampl
You may install the library and library headers in a location other than extra/ampl/solvers. If configure is unable to determine the location of these files, you will need to set the AMPL_SOLVERS environment variable. See ENVIRONMENT VARIABLES AND configure for information on how to do so.
OOQP may be invoked from within Matlab. Instructions on how to build this interface may be found in the README_Matlab file.
Some solvers in OOQP use the PETSc package from Argonne National Laboratory to perform linear algebra operations. Before the OOQP-PETSc interface can be build, you must install PETSc on your system. See the PETSc home page at http://www.mcs.anl.gov/petsc/index.html for information.
Once PETSc has been installed, run the OOQP configure script, as usual. Then type
make -f PetscMakefile all_petsc
As part of the PETSc installation process you will set certain environment variables, such as PETSC_DIR and BOPT. These must remain set while building the OOQP-PETSc interface. These variables are used by the PETSc build system, and are not under the control of the OOQP build system. We have decided to conform to the PETSc build system as much as possible when building this interface.
TAO is the Toolkit for Advanced Optimization, a software package for optimization developed at Argonne National Laboratory. The TAO home page is http://www.mcs.anl.gov/tao/
OOQP may be invoked as a solver from within TAO. This interface is maintained jointly by the TAO and OOQP developers, and is distributed with TAO, rather than with OOQP. The current version of this interface uses PETSc to perform its underlying linear algebra operations. Before you build the OOQP-TAO interface, you must build the OOQP-PETSc interface as described above.
F2C is a FORTRAN to C translator that may be obtained from http://www.netlib.org/f2c. We have had no difficulty compiling OOQP using the output from this translator. We recommend using F2C if you are having difficulty compiling OOQP using your FORTRAN compiler (or if you don't have a FORTRAN compiler.)
Once the f2c translator is installed, you may type
f2c *.f
in any directory containing FORTRAN files that you wish to translate. The OOQP build system will try to compile the translated C files, rather than the original FORTRAN files. (Actually, this behavior is not unique to OOQP, but is rather a default of GNU make.) You must be sure that the compiler can find the include file f2c.h. You may, for instance, copy this include file into any directory containing translated FORTRAN files.
If you are using f2c instead of a FORTRAN compiler, be sure to set the FLIBS environment to point to the F2C library, which is typically named libf2c.a. Then run configure like this
./configure --without-fortran
so that configure knows not to check the properties of the FORTRAN compiler.
Many compilers perform useful optimizations. These optimizations are
specified by particular compiler flags. The configure script doesn't ask
the compiler to perform any optimizations beyond the basic ones indicated
by the compile flag -O.
Users who are aware of a good set of compiler flags may wish to set the following environment variables before running configure:
FFLAGS -- Compiler flags for the Fortran compiler.
CFLAGS -- Compiler flags for the C compiler.
CXXFLAGS -- compiler flags for the C++ compiler.
The libraries and executables will be built using those flags. Of particular importance are the flags used to compile MA27 or MA57. Also, the quality of the BLAS library can affect performance greatly, so use an optimized version where possible.
We have found the following flags useful on the following systems:
Set FFLAGS, CFLAGS and CXXFLAGS to -funroll-loops -O3 -mcpu=i586
Set FFLAGS, CFLAGS and CXXFLAGS to -fast
After building the executables and libraries, you may use them directly from within the current directory. Optionally, you may install them in a more permanent location. If you type
make install
(after running the configure script), the make utility attempts to install the executables and libraries into the /usr/local directory tree. Of course, you will be unable to install to this location unless you have privileged access to the machine. Furthermore, even if you have privileged access, your system administrator may require you to install new packages in a different location.
If you are unsure that the package should be installed in /usr/local, we
recommend that you install in $HOME/software (the pattern
$HOME will be expanded to the full path of your home
directory). You can do this by typing:
./configure --prefix=$HOME/software
make install
The PREFIX variable will now be set to the value you have assigned in the configure option (in this case $HOME/software).
The following items will be installed:
The OOQP libraries will be installed in $PREFIX/lib.
The OOQP headers will be installed in $PREFIX/include/ooqp.
The OOQP executables will be installed in $PREFIX/bin.
The OOQP documentation will be installed in $PREFIX/share/doc/packages/ooqp.
This could occur because your system does not have the environment needed to build OOQP. (For instance, your FORTRAN compiler cannot create executables.) It could also be a bug in the configure script. If you suspect the latter, please contact the OOQP developers.
If typing ``make'' results in
make: Fatal error: No arguments to build
or some similar message, then the version of make that you are using is probably not GNU make. Try typing ``gmake'' instead. If this also fails, it is likely that GNU make is not installed on your system. See PREREQUISITES for more information. Back to the Documentation Roadmap .