installdoc.html.svn-base

OPT++

/** \page InstallDoc 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.

<ol>
  <li> <a href ="#installbasics"> Installation - The Basics</a> <br>
  <li> \ref configuration <br>
     <ul>
     <li> <a href="#general"> Generally useful configuration commands</a> <br>
     <li> <a href="#compiler"> Configuring for a particular compiler</a> <br>
     <li> <a href="#blas"> Configuring for a particular BLAS library</a> <br>
     <li> <a href="#parallel"> Configuring for parallel use</a> <br>
     <li> <a href="#npsol"> Configuring to use NPSOL</a> <br>
     <li> <a href="#documentation"> Configuring to build HTML documentation</a> <br>
     </ul>
  <li> <a href = "#make"> Step 2 - Making </a><br>
  <li> <a href = "#test"> Step 3 - Testing </a><br>
  <li> <a href = "#usage"> Using OPT++</a><br>
  <li> <a href = "#platforms"> Platform Information </a><br>
  <li> <a href = "#issues"> Known Issues </a><br>
  <li> <a href = "#disclaimer"> The Standard Absolution of Responsibility</a><br>
</ol>

\section installbasics 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.

<ol>
	<li> cd optpp-2.4
	<li> ./configure 
	<li> make >& make.log
	<li> make check >& makecheck.log
	<li> make install
</ol>

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 <a
href="http://software.sandia.gov/bugzilla"> Bugzilla</a>.

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

       \verbatim
          ./configure
       \endverbatim

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.

<a name="general"><em> Generally useful configuration commands </em></a>

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

       \verbatim
          ./configure --help
       \endverbatim

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

       \verbatim
          ./configure --prefix=directory_to_install_OPT++
       \endverbatim

<a name="compiler"><em> Configuring for a particular compiler </em></a>

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.

<ol>
	<li> The first is at configure time.  Use the command
       \verbatim
          ./configure CXX=<C++ compiler> CC=<C compiler> F77=<F77 compiler>
       \endverbatim

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

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

       \verbatim
          export CXX=<C++ compiler>
	  export CC=<C compiler>
	  export F77=<F77 compiler>
       \endverbatim

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

       \verbatim
          setenv CXX <C++ compiler>
	  setenv CC <C compiler>
	  setenv F77 <F77 compiler>
       \endverbatim

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

       \verbatim
          ./configure
       \endverbatim

</ol>

<a name="blas"><em> Configuring for a particular BLAS library </em></a>

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 <a href = "#issues">"Known Issues"</a> 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.

<ol>
	<li> The first is on the command line for configure.  For
	   example,

       \verbatim
          ./configure --with-blas=/path/to/blas/blaslibraryname.a
       \endverbatim

	   Note that you must include the name of the library.

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

       \verbatim
          export BLAS_LIBS=/path/to/blas/blaslibraryname.a
       \endverbatim

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

       \verbatim
          setenv BLAS_LIBS /path/to/blas/blaslibraryname.a
       \endverbatim

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

       \verbatim
          ./configure
       \endverbatim
</ol>

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

       \verbatim
          ./configure --without-blas
       \endverbatim

<a name="parallel"><em> Configuring for parallel use </em></a>

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: <a href="http://www-unix.mcs.anl.gov/mpi/mpich2/">http://www-unix.mcs.anl.gov/mpi/mpich2/</a> <br>
	  openMPI: <a href ="http://www.open-mpi.org/">http://www.open-mpi.org/</a>

Older versions that are only maintained include:

          mpich1: <a href="http://www-unix.mcs.anl.gov/mpi/mpich1/">http://www-unix.mcs.anl.gov/mpi/mpich1/</a> <br>
	  LAM MPI: <a href="http://www.lam-mpi.org/">http://www.lam-mpi.org/</a> <br>
	  LA-MPI: <a href="http://public.lanl.gov/lampi/">http://public.lanl.gov/lampi/</a> <br>

To configure for parallel use, use the command

       \verbatim
          ./configure --enable-mpi
       \endverbatim

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.

<ol>
	<li> The first is to set the environment variables on the
	   command line for configure.  For example,

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

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

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

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

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

       \verbatim
          setenv MPICXX <MPI C++ compiler>
	  setenv MPICC <MPI C compiler>
	  setenv MPIF77 <MPI F77 compiler>
       \endverbatim

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

       \verbatim
          ./configure --enable-mpi
       \endverbatim
</ol>

<a name="npsol"><em> Configuring to use NPSOL </em></a>

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 <a
href="http://www.sbsi-sol-optimize.com/NPSOL.htm">http://www.sbsi-sol-optimize.com/NPSOL.htm</a>

To configure for use with NPSOL, use the command

       \verbatim
          ./configure --with-npsol
       \endverbatim

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.

<ol>
	<li> The first is on the command line for configure.  For
	   example,

       \verbatim
          ./configure --with-npsol=/path/to/npsol/npsollibraryname.a
       \endverbatim

	   Note that you must include the name of the library.

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

       \verbatim
          export NPSOL_LIB=/path/to/npsol/npsollibraryname.a
       \endverbatim

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

       \verbatim
          setenv NPSOL_LIB /path/to/npsol/npsollibraryname.a
       \endverbatim

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

       \verbatim
          ./configure --with-npsol
       \endverbatim
</ol>

<a name="documentation"><em> Configuring to build HTML documentation </em></a>

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 <a
href="http://www.stack.nl/~dimitri/doxygen/">http://www.stack.nl/~dimitri/doxygen/</a>

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

       \verbatim
          ./configure --enable-html-docs
       \endverbatim

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.

<ol>
	<li> The first is on the command line for configure.  For
	   example,

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

	   Note that you must include the name of the executable.

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

       \verbatim
          export DOXYGEN=path/to/doxygen/doxygen
       \endverbatim

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

       \verbatim
          setenv DOXYGEN path/to/doxygen/doxygen
       \endverbatim

	   As before, you must include the name of the executable.