installdoc.html.svn-base

OPT++

	   Then simply, type

       \verbatim
          ./configure --enable-html-docs
       \endverbatim
</ol>

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 <a
href="http://csmr.ca.sandia.gov/projects/opt++">OPT++ web page</a>.

\section make Step 2 - Making

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

       \verbatim
          make
       \endverbatim

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

       \verbatim
          make >&! make.log
       \endverbatim

If there are errors in the build, please report the problem to the
authors via <a href="http://software.sandia.gov/bugzilla">
Bugzilla</a>.  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

       \verbatim
          make check
       \endverbatim

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

       \verbatim
          make check >& check.log
       \endverbatim

The regression tests are discussed further in the <a href="#test">
Testing</a> 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

       \verbatim
          make install
       \endverbatim

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

       \verbatim
          make clean
       \endverbatim

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

       \verbatim
          make distclean
       \endverbatim

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 <a href="#usage"> Using OPT++</a>
section.  A more extensive tutorial can be found in the <a
href="SetUp.html"> Setting up and Solving an Optimization Problem</a>
section.

\section test 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

       \verbatim
          make check >& check.log
       \endverbatim

If any of the tests failed, report problems to the authors via <a
href="http://software.sandia.gov/bugzilla"> Bugzilla</a>.  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).

\section usage Using OPT++

We recommend looking at the <a href="SetUp.html"> Setting up and
Solving an Optimization Problem</a> 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:

<ol>
	<li> Construct the problem object, which includes pointers to the
	   subroutines that initialize and evaluate the objective
	   function and the constraints.
	<li> Construct the object corresponding to the algorithm to be
	   used and set any algorithmics parameters.
	<li> Call the optimization method.
</ol>

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.

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

       \verbatim
          -DHAVE_STD
       \endverbatim

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

       \verbatim
          -DHAVE_NAMESPACES
       \endverbatim

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

       \verbatim
          -DWITH_MPI
       \endverbatim

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

       \verbatim
          -DMPICH_IGNORE_CXX_SEEK
       \endverbatim

	<li> 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

       \verbatim
          -IOPT++_install_directory/include
       \endverbatim

	   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

       \verbatim
          -IOPT++_top_directory/include -IOPT++_top_directory/newmat11
       \endverbatim

	<li> 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

       \verbatim
          -LOPT++_install_directory/lib
       \endverbatim

	   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

       \verbatim
          -LOPT++_top_directory/lib/.libs
       \endverbatim

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

	<li> If all is right in the world, the following format for
	   your compilation command should work:

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

	   $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.
</ol>

And, of course, if you have problems, report them to the authors via
<a href="http://software.sandia.gov/bugzilla">Bugzilla</a>.  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 <a
href="SetUp.html"> Setting up and Solving an Optimization Problem</a>
section.

\section platforms Platform Information

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

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

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.

\section issues Known Issues

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

<ol>
	<li> 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.

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

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

	<li> 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.
</ol>

\section disclaimer 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 <a href="http://sofware.sandia.gov/bugzilla">Bugzilla</a>,
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.

<p> Next Section:  \ref SetUp | Back to the <a href="index.html"> Main
Page</a> </p>

Last revised <em> May 1, 2007</em>


*/