Installation

The following sections contain instructions for compiling and testing OPT++. The basic instructions are followed by more detailed explanations of each step in the process. A brief summary of how to use OPT++ appears at the end; however, we encourage the user to continue reading the documentation for more extensive details. The following topics are covered on this page.

  1. Installation - The Basics
  2. Step 1 - Configuring
  3. Step 2 - Making
  4. Step 3 - Testing
  5. Using OPT++
  6. Platform Information
  7. Known Issues
  8. The Standard Absolution of Responsibility

Installation - The Basics

The installation procedure is based on the GNU Autotools. You should be able to configure OPT++ for your particular system and then type make in the top level directory. There is also a set of regression tests that you can build and run.

If you are in a real hurry or one of the truly impatient, the following 5 command lines should get you going on most systems.

  1. cd optpp-2.4
  2. ./configure
  3. make >& make.log
  4. make check >& makecheck.log
  5. make install

Note that the final step will install OPT++ in /usr/local, and thus, you must have root privileges in order to execute that step successfully. Be sure to examine the make.log and check.log files to ensure that the build was successful and that the regression tests passed. Report any problems via Bugzilla.

Additional options and further details about configuring and building OPT++ appear in the following sections. A brief overview of how to use OPT++ can be found in the Using OPT++ section. A more extensive tutorial can be found in the Setting up and Solving an Optimization Problem section.

Step 1 - Configuring

The purpose of the configuration step is to create the Makefile that will build a version of OPT++ that is appropriate for the system on which you intend to use it. The simplest form of the command is

          ./configure
       

This uses the default settings, and the resulting configuration can be found in the "config.log" and "config.status" files.

There are a number of options that you can set during the configuration process. Each requires adding a flag to the configure command. You can add as many flags as required to obtain the desired configuration. The most useful and common configuration options for OPT++ are described below.

Generally useful configuration commands

There are a number of options that you can set during the configuration process. To see them all, you can use the command

          ./configure --help
       

If you wish to install OPT++ in a directory other than /usr/local, the configuration command should look something like the following:

          ./configure --prefix=directory_to_install_OPT++
       

Configuring for a particular compiler

For most operating systems, there are multiple compilers that can be used. The default configure behavior is to use the GNU compilers if they are installed on your system. If not, configure will search for a number of other common compilers. This behavior can be overridden by setting the CXX, CC, and F77 environment variables. If these variables are set, those are the compilers that will be used. There are two ways to specify the values of CXX, CC, and F77 to configure.

  1. The first is at configure time. Use the command
              ./configure CXX=<C++ compiler> CC=<C compiler> F77=<F77 compiler>
           

    Note that if these compilers do not appear in your path, you must specify the full path.

  2. The other means of specifying alternate compilers is to set the CXX, CC, and F77 environment variables before you execute configure. If you are using the bash shell, do

              export CXX=<C++ compiler>
    	  export CC=<C compiler>
    	  export F77=<F77 compiler>
           

    to set these variables. If you are using csh or tcsh, do

              setenv CXX <C++ compiler>
    	  setenv CC <C compiler>
    	  setenv F77 <F77 compiler>
           

    As in the first case, you must specify the full path if the compilers do not already appear in your path. Then simply, type

              ./configure
           

Configuring for a particular BLAS library

OPT++ makes use of a few BLAS routines. At the configure stage, it will search for a BLAS library on your system. The default behavior is to look for the following libraries (depending on the platform you are building on): ATLAS library, PhiPACK library, Alpha CXML library, Alpha DXML library, Sun Performance Library, SGI/CRAY SCSL library, SGIMATH library, IBM ESSL library, and generic BLAS library. (Please see the "Known Issues" section for issues associated with detecting BLAS libraries.) If it finds one of these libraries at configure time, that is the BLAS library that will be used. If none of these are found, OPT++ will fall back on its own implementation of the needed BLAS routines. If you would like to use a BLAS library other than those listed above, you can specify the name of that library by setting the BLAS_LIBS environment variable. That can be done in one of two ways.

  1. The first is on the command line for configure. For example,

              ./configure --with-blas=/path/to/blas/blaslibraryname.a
           

    Note that you must include the name of the library.

  2. The other means of specifying the BLAS library to use is to set the BLAS_LIBS environment variable before you execute configure. If you are using the bash shell, do

              export BLAS_LIBS=/path/to/blas/blaslibraryname.a
           

    to set this variable. If you are using csh or tcsh, do

              setenv BLAS_LIBS /path/to/blas/blaslibraryname.a
           

    As before, you must include the name of the library. Then simply, type

              ./configure
           

Finally, if you wish to not use any BLAS library and instead use the OPT++ implementation, use the following form of configure statement:

          ./configure --without-blas
       

Configuring for parallel use

The default configuration builds OPT++ to run serially; however, OPT++ does have algorithms the leverage parallelism should you wish to take advantage of that capability. Parallelism is achieved through the use of MPI. The assumption is that an implementation of MPI is already installed somewhere on your system. If it is not, there are a number of open source versions you can download and install. Those under active development include:

mpich2: http://www-unix.mcs.anl.gov/mpi/mpich2/
openMPI: http://www.open-mpi.org/

Older versions that are only maintained include:

mpich1: http://www-unix.mcs.anl.gov/mpi/mpich1/
LAM MPI: http://www.lam-mpi.org/
LA-MPI: http://public.lanl.gov/lampi/

To configure for parallel use, use the command

          ./configure --enable-mpi
       

This will look for a number of both open source and vendor implementations of the MPI compilers. If none are found, the parallel version of OPT++ will not be built. If the MPI compilers are not in your path or if you wish to use a particular version of MPI, you can specify the MPI compilers to use by setting the MPICXX, MPICC, and MPIF77 environment variables. If these variables are set, those are the compilers that will be used. There are two ways to specify the values of MPICXX, MPICC, and MPIF77 to configure.

  1. The first is to set the environment variables on the command line for configure. For example,

              ./configure --enable-mpi MPICXX=<MPI C++ compiler> \
    	              MPICC=<MPI C compiler> MPIF77=<MPI F77 compiler>
           

    Note that if these compilers do not appear in your path, you must specify the full path.

  2. The other means of specifying alternate compilers is to set the MPICXX, MPICC, and MPIF77 environment variables before you execute configure. If you are using the bash shell, do

              export MPICXX=<MPI C++ compiler>
    	  export MPICC=<MPI C compiler>
    	  export MPIF77=<MPI F77 compiler>
           

    to set these variables. If you are using csh or tcsh, do

              setenv MPICXX <MPI C++ compiler>
    	  setenv MPICC <MPI C compiler>
    	  setenv MPIF77 <MPI F77 compiler>
           

    As in the first case, you must specify the full path if the compilers do not already appear in your path. Then simply, type

              ./configure --enable-mpi
           

Configuring to use NPSOL

The default configuration constructs a Makefile that will build OPT++ without any knowledge of NPSOL; however, OPT++ does have a wrapper for NPSOL should you wish to use it. (Please see the "Known Issues" section at the end of this file for issues associated with including NPSOL.) The assumption is that NPSOL is already installed somewhere on your system. If it is not, you must install it. You can find more information about NPSOL at http://www.sbsi-sol-optimize.com/NPSOL.htm

To configure for use with NPSOL, use the command

          ./configure --with-npsol
       

This will look for libnpsol.a and npsol.a in /usr/local/lib and /usr/lib. If it does not find one of those libraries in one of those locations, OPT++ will fall back on the default behavior of not including NPSOL. You can specify an alternate location and/or library name for NPSOL by setting the NPSOL_LIB environment variable. There are two ways to do this.

  1. The first is on the command line for configure. For example,

              ./configure --with-npsol=/path/to/npsol/npsollibraryname.a
           

    Note that you must include the name of the library.

  2. The other means of specifying an alternate NPSOL library is to set the NPSOL_LIB environment variable before you execute configure. If you are using the bash shell, do

              export NPSOL_LIB=/path/to/npsol/npsollibraryname.a
           

    to set this variable. If you are using csh or tcsh, do

              setenv NPSOL_LIB /path/to/npsol/npsollibraryname.a
           

    As before, you must include the name of the library. Then simply, type

              ./configure --with-npsol
           

Configuring to build HTML documentation

As already mentioned, OPT++ comes with HTML documentation. The default behavior does not build the HTML documentation, but you can configure OPT++ to build it when you build the libraries. In order to do this, doxygen must be installed on your system. Doxygen is standard in most unix distributions, but if it is not installed, you can download it at http://www.stack.nl/~dimitri/doxygen/

To configure OPT++ to build the HTML documentation, simply type

          ./configure --enable-html-docs
       

This assumes that doxygen appears in your path. If it does not, you can specify the location using the DOXYGEN environment variable. There are two ways to do this.

  1. The first is on the command line for configure. For example,

              ./configure --enable-html-docs DOXYGEN=path/to/doxygen/doxygen
           

    Note that you must include the name of the executable.

  2. The other means of specifying an alternate doxygen executable is to set the DOXYGEN environment variable before you execute configure. If you are using the bash shell, do

              export DOXYGEN=path/to/doxygen/doxygen
           

    to set this variable. If you are using csh or tcsh, do

              setenv DOXYGEN path/to/doxygen/doxygen
           

    As before, you must include the name of the executable. Then simply, type

              ./configure --enable-html-docs
           

The HTML documentation will then automatically be built when you do 'make'. To access it, use your favorite browser to open the file OPT++/docs/html/index.html.

Alternatively, you can obtain the HTML documentation by downloading the tar file, docs.tgz, from the OPT++ web page.

Step 2 - Making

Once it has been configured, building OPT++ is straightforward. From the top-level OPT++ directory, simply issue the command

          make
       

As a slight modification, we recommend directing the output to a file so the output can be more closely examined for errors. In this case, the command becomes

          make >&! make.log
       

If there are errors in the build, please report the problem to the authors via Bugzilla. Please include the log file as well as complete information about your system (the output from the command "uname -a" and the compiler/version).

Once you have built OPT++, we recommend that you run the regression tests. You can do this by typing

          make check
       

Again, we recommend you direct the output to a file, i.e.

          make check >& check.log
       

The regression tests are discussed further in the Testing section. In the meantime, there are a number of other useful make options available.

In order to install OPT++ in /usr/local or another directory specified at configure time, type

          make install
       

In order to remove object files and the libraries that were created during make, type

          make clean
       

To remove not only the files mentioned above, but also the Makefiles and other files generated during the configure, issue the command

          make distclean
       

A description of the regression tests follows in the next section. If, however, you are anxious to get started, a brief overview of how to use OPT++ can be found in the Using OPT++ section. A more extensive tutorial can be found in the Setting up and Solving an Optimization Problem section.

Step 3 - Testing

It is strongly recommended that you run the regression tests to ensure that OPT++ operates correctly on your machine. From the top-level OPT++ directory, type

          make check >& check.log
       

If any of the tests failed, report problems to the authors via Bugzilla. Please include the log file and the output from the failed test, as well as complete information about your system (the output from the command "uname -a" and the compiler/version).

Using OPT++

We recommend looking at the Setting up and Solving an Optimization Problem section to learn how to set up and solve optimization problems with OPT++. However, for those who like to jump right in, there are plenty of examples in the tests/* directories. By mimicking their form, you will likely be able to get your problem up and running. A word of warning - the code in the example files is not particularly well documented. The examples are fully documented in the HTML documentation.

In short, there are several things the user must provide. The first is a main routine written in C++. In this routine, the user must do the following:

  1. Construct the problem object, which includes pointers to the subroutines that initialize and evaluate the objective function and the constraints.
  2. Construct the object corresponding to the algorithm to be used and set any algorithmics parameters.
  3. Call the optimization method.

In addition to the main routine, the user must provide the C++ subroutines that perform the initializations and the evaluations of the functions and the constraints. (Note: These C++ subroutines may be wrappers to C or Fortran subroutines or to system calls.) As mentioned before, there are many examples in the tests/* directories, and they are thoroughly documented in the HTML documentation.

Building your executable should be fairly straightforward. Below is the recommended set of steps to follow.

  1. Determine which defines you need. If the C++ compiler you are using supports the ANSI standard style of C header files, you will need

              -DHAVE_STD
           

    If the C++ compiler you are using supports namespaces, you will need

              -DHAVE_NAMESPACES
           

    If you are using the parallel version of OPT++, you will need

              -DWITH_MPI
           

    If you are using the parallel version of OPT++ with MPICH2, you may additionally need

              -DMPICH_IGNORE_CXX_SEEK
           

  2. Determine the location of the header files. If you did a "make install", they will be located in the "include" subdirectory of the directory in which OPT++ is installed. If that directory is not one your compiler normally checks, you will need

              -IOPT++_install_directory/include
           

    If you did not do a "make install", the header files will almost certainly be in a directory not checked by your compiler. Thus, you will need

              -IOPT++_top_directory/include -IOPT++_top_directory/newmat11
           

  3. Determine the location of the libraries. If you did a "make install", they will be located in the "lib" subdirectory of the directory in which OPT++ is installed. If that directory is not one your compiler normally checks, you will need

              -LOPT++_install_directory/lib
           

    If you did not do a "make install", the libraries will almost certainly be in a directory not checked by your compiler. Thus, you will need

              -LOPT++_top_directory/lib/.libs
           

  4. If you configured OPT++ for the default behavior of using the BLAS and/or you configure OPT++ to use NPSOL, you will need the appropriate Fortran libraries for linking. The easiest way to get these is to look in the Makefile for the value of FLIBS.

  5. If all is right in the world, the following format for your compilation command should work:

              $CXX <defines> <includes> myMain.C myF.C <lib \
    	  directory> -lopt -lnewmat -l$BLAS_LIB $FLIBS 
           

    $CXX is the C++ compiler you are using. <defines> and <includes> are the flags determined in steps 1-2. myMain.C is your main routine, and myF.C contains your function evaluations. (Note: If you have put them both in one file, you need only list that single file here.) <lib_directory> was determined in step 3. -lopt and -lnewmat are the two OPT++ libraries. $BLAS_LIB is the BLAS library you are using, and $FLIBS is the list of Fortran libraries determined in step 4.

And, of course, if you have problems, report them to the authors via Bugzilla. Please include the log file and the output from the failed test, as well as complete information about your system (the output from the command "uname -a" and the compiler/version).

A more extensive tutorial on using OPT++ can be found in the Setting up and Solving an Optimization Problem section.

Platform Information

The serial version of OPT++ has been built and tested on the following platforms:

ARCH OS COMPILER
i686 Linux 2.4.21-*
Linux 2.6.9-*
Linux 2.6.20-*
GNU 3.2.2, 3.2.3, 3.4.3, 3.4.5, 3.4.6, 4.0.2, 4.1.1
Intel 8.1, 9.0
PGI 5.2, 6.0, 6.2
i686 Cygwin 1.5.20-1
Cygwin 1.5.25
GNU 3.4.4
x86_64 (Intel) Linux 2.6.9-34.0.2
GNU 3.4.5
x86_64 (AMD) Linux 2.4.21-37
Linux 2.6.9-42.0.2
GNU 3.2.2, 3.2.3, 3.4.3, 3.4.6
Intel 8.1, 9.0, 9.1
PGI 6.2
Mac PowerPC OS X 10.3.9
GNU 3.3
SUN Solaris 2.10 CC/cc 5.7
GNU 3.3.2
SGI IRIX 6.5 CC/cc MIPSPro 7.4.2
IBM AIX 5.2 xlC/xlc 7.0

It is possible the OPT++ will also build with the MinGW compilers and the Microsoft compilers; however, there are no guarantees. OPT++ is not yet stable on those platforms and has not been fully tested.

The parallel version of OPT++ has only been built and tested on an Intel Linux machine with OpenMPI 1.1, MPICH2 1.0.3, MPICH 1.2.7p1, LAM MPI 7.1.2, and LA-MPI 1.5.15; however, we expect it will work on the above-supported platforms with other versions and implementations of MPI. The GUI/XML interface has only been tested on Intel Linux machines.

Known Issues

Alas, there a few issues that we are aware of:

  1. BLAS: The m4 macro that we obtained to detect BLAS libraries is a few years old, so there are a couple of cases where they are not detected correctly.

    We will work on correcting these issues.

  2. NPSOL: We had problems linking in NPSOL on the MAC platform. Try explicitly setting your FLIBS environment variable to "-L/sw/lib -lfrtbegin -lg2c -lm -lgcc". That may or may not do the trick.

    We also had problems linking NPSOL with the GNU 4.0.2 compilers. We will keep working on both these issues.

  3. XML/GUI: The XML and GUI interface has not been updated yet, so it is currently not available with this version. We will get this finished and distribute a patch file as quickly as we can.

  4. PGI Compilers: In our testing, we found that autotools was adding an invalid item to the list of libraries when using the PGI compilers. This causes the build of the test problems to break. We have not yet isolated the problem, but in the the meantime, it is an easy fix. If "make check" fails, go into the "Makefile" in each of the test directories (tests/constraints, tests/hock, tests/npsol, tests/parallel, and tests/uncon) and search for "FLIBS". Delete the first entry in the list, "-lm'"...it is that extra single quote that is the culprit. Then try "make check" again.

The Standard Absolution of Responsibility

WARNING: This is RESEARCH code, and we all know what that means! While it should run on most UNIX platforms with ANSI-compliant C++/C compilers, there are no guarantees. On the bright side, we are happy to improve the reliability of the code. Please report bugs to the authors via Bugzilla, including complete information about your system (the output from the command "uname -a" and the compiler/version), the exact error messages generated, and any output produced. If possible, a small piece of code that generates the bug would be most helpful.

Next Section: Setting up and Solving an Optimization Problem | Back to the Main Page

Last revised May 1, 2007


Bug Reports    OPT++ Developers    Copyright Information    GNU Lesser General Public License
Documentation, generated by , last revised August 30, 2006.