INSTALL

			OPT++ 2.4
	 A Nonlinear Optimization Package in C++.

---------------------------------------------------------------------------

Authors:  Juan C. Meza
	  Lawrence Berkeley National Laboratory

	  Patricia D. Hough
	  Sandia National Laboratories

	  Pamela J. Williams
	  Sandia National Laboratories

	  Ricardo A. Oliva
	  Sabio Labs

Bug Reports:  http://software.sandia.gov/bugzilla

Contact:  opt++-developers@software.sandia.gov

URLs:  http://csmr.ca.sandia.gov/projects/opt++
       http://www.nersc.gov/~meza/projects/opt++

Thanks to Sherae Daniel of the University of Maryland and Andrew
Rothfuss of Sandia National Labs for help with the GUI/XML interface.
Thanks also to Edward Walsh and Shane Brown, both of Sandia National
Labs, for their assistance in converting the build system to
autotools.

---------------------------------------------------------------------------

Description

OPT++ is a C++ library of nonlinear optimization algorithms.  The
motivation for this package is to build an environment for the rapid
prototyping and development of new optimization algorithms.  In
particular, the focus is on robust and efficient algorithms for
problems in which the function and constraint evaluations require the
execution of an expensive computer simulation.

OPT++ has been copyrighted by Sandia Corporation and is freely
distributed under GNU General Public License.  Please see the README,
COPYRIGHT, and GNU_GPL files in this directory for more information.

---------------------------------------------------------------------------

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 3 commands 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
(http://software.sandia.gov/bugzilla).

Additional options and further details about configuring, building,
and using OPT++ appear below.  In addition, this information can be
found in the complete HTML documentation.

You can obtain the HTML documentation in one of two ways.  The first
is to download the tar file, docs.tgz, from the OPT++ web page
(http://csmr.ca.sandia.gov/projects/opt++) and follow the included
instructions.  This tar file contains the pre-built HTML files.  The
alternative is to build the documnentation with doxygen.  To do this,
modify step 2 above to the following:

	./configure --enable-html-docs

The HTML documentation will then automatically be built in step 3 if
doxygen is installed on your system.  To access it, use your favorite
browser to open the file OPT++/docs/html/index.html.

---------------------------------------------------------------------------

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 to set the environment variables on the
	   command line for configure.  For example,

	   ./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 at the end of this file 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 with 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
(http://csmr.ca.sandia.gov/projects/opt++).

---------------------------------------------------------------------------

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 (http://software.sandia.gov/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 next 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

---------------------------------------------------------------------------

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 (http://software.sandia.gov/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 making use of the HTML documentation in order 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 (http://software.sandia.gov/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).

---------------------------------------------------------------------------

Platform Information

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

ARCH	OS				COMPILER

i686	Linux 2.4.21-*			GNU 3.2.2, 3.2.3, 3.4.3,
	Linux 2.6.9-*			3.4.5, 3.4.6, 4.0.2, 4.1.1
	Linux 2.6.20-*	 		Intel 8.1, 9.0
					PGI 5.2, 6.0, 6.2

i686	Cygwin 1.5.20-1			GNU 3.4.4
	Cygwin 1.5.24

x86_64	Linux 2.6.9-34.0.2		GNU 3.4.5
(Intel)

x86_64	Linux 2.4.21-37			GNU 3.2.2, 3.2.3, 3.4.3, 3.4.6
(AMD)	Linux 2.6.9-42.0.2		Intel 8.1, 9.0, 9.1
					PGI 6.2

Mac	OS X 10.3.9			GNU 3.3
(PowerPC)

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.  It 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.

		- Intel compilers (icpc/icc) - The Math Kernel
		  Libraries (MKL) are not detected.  If you want to
		  make use of the BLAS from MKL, you will have to set
		  the BLAS_LIBS environment variable to the
		  appropriate path.
		- MAC OS X - The BLAS are implemented a little
		  differently on the MAC.  In particular, they are
		  implemented as frameworks and thus not detected as
		  libraries.  If you want to use the native MAC
		  implementation, set the LDFLAGS environment variable
		  to "-framework vecLib".
		- SUN compilers (CC/cc) - Depending on which version
		  of the compilers you have, you may or may not have a
		  problem.  The macro does not take into account some
		  recent changes associated with the newer
		  implementations.  If there are problems, they will
		  show up at link time.  In that case, try setting the
		  BLAS_LIBS environment variable to
		  "/opt/SUNWspro/lib/libsunperf.so".

	   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.

---------------------------------------------------------------------------

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 (http://sofware.sandia.gov/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.