TAO

Documentation: Installation

Installing TAO should take less than an hour. We support its use on any of the following architectures:

  • Windows (under cygwin)
  • Apple OS X
  • Pentium class processors running Linux or freebsd
  • IBM RS6000 (including SP)
  • SGI Workstations
  • SGI Origin
  • Sun Sparcstations running Solaris
  • Cray T3E

TAO uses a portable makefile system provided by the PETSc library; thus, refer to PETSc installation support for details about these machines.

Note for Windows Users

The following installation instructions are intended to be run from the unix command line. To install under Windows, the Cygwin environment must be installed. Download and installation information can be found at http://www.cygwin.com. The following Cygwin packages are required:

  • Utils -- patch
  • Utils -- rebase
  • Interpreters -- python
  • Devel -- make
  • Devel -- gcc-g++
    • (if no Microsoft, Intel, or Borland C++ compiler available)

TAO must be compiled with a C++ compiler and requires a minimum of 60 Mbytes of disk space to install.

Installing TAO:

  • Prior to installing TAO, the machine must have a working installation of the PETSc software package, available via http://www.mcs.anl.gov/petsc. TAO uses portable makefile capabilities as well as parallel linear algebra support within PETSc. The current version of TAO (1.10) requires version 3.0.0 of PETSc.
    PETSc MUST be configured with the option
    • --with-clanguage=C++
    Do NOT configure PETSc with any of the following:
    • --with-clanguage=C
    • --with-precision=single
    • --with-precision=matsingle
    • --with-scalar-type=complex
    Other useful PETSc options are:
    • --with-debugging compiles with information for debugging
    • --with-shared creates shared libraries
    • --with-fortran creates and installs Fortran wrappers
    • --with-mpi-dir=<dir> indicates the root directory of your MPI installation if already installed
    • --download-mpich automatically download and install MPICH-2
    • --download-f-blas-lapack automatically download and install BLAS and LAPACK libraries if Fortran compiler available
    • --download-c-blas-lapack automatically download and install BLAS and LAPACK libraries if no Fortran compiler available

      • Run the PETSc example programs before proceeding further.

    • Set the PETSc environment variables
      • Set the environmental variable PETSC_DIR to the full path of the PETSc home directory, for example,
        setenv PETSC_DIR /home/username/petsc-3.0.0
        (export PETSC_DIR=/home/username/petsc-3.0.0 for bash shells)
      • Set the environmental variable PETSC_ARCH, which indicates the architecture on which PETSc was configured. If you are unsure what value you should use for PETSC_ARCH, a listing of the directory ${PETSC_DIR}/lib will give you your available choices. For example:
        setenv PETSC_ARCH linux-gnu
        (export PETSC_ARCH=linux-gnu for bash shells)

    • Unbundle the TAO distribution with
      gunzip -c tao-1.9.tar.gz | tar -xvf -
      By default, this will create a directory called tao-1.9 and unpack the software there.

    • Set the environmental variable TAO_DIR to the full path of the TAO home directory, for example,
      setenv TAO_DIR /home/username/tao-1.9
      (export TAO_DIR=/home/username/tao-1.9 for bash shells)
      Users may want to set this variable in their .cshrc or .bashrc file.
  • In the TAO home directory, type
    make all
    to build the TAO libraries.
  • Check the output from the installation to determine whether any errors occurred during the installation process. Try to fix any errors, and let us know what they were. But first see the file bug reporting for help with common problems. If errors have been encountered and you would like assistance from the TAO developers, then redirect all output from the installation to a file, for example, using the command
    make all >& make.log
    and send this to us as discussed in the bug reporting instructions.

Test Programs:

  • If the installation went smoothly, then try running some test examples with the command
    make tao_testexamples >& examples_log
  • If only the uniprocessor version of TAO has been installed (i.e., MPI has not been installed), then use the following command to run only sequential examples:
    make tao_testexamples_uni >& examples_log
  • Examine the file examples_log for any obvious errors or problems.
  • The examples can be manually built and run one at a time by changing to the appropriate directory (for instance, ${TAO_DIR}/src/unconstrained/examples/tutorials) and running commands such as
    make minsurf1
    make runminsurf1 (or, for example, mpirun minsurf1)
    This alternative may be preferable if "make tao_testexamples" fails for some reason.
  • The automatic tests may not work on systems that use a queue and special commands to run parallel jobs. Instead, the user can compile and run the examples manually as discussed above.

Fortran Users:

The TAO Fortran libraries are built automatically during the installation outlined above. Before testing the Fortran examples, please make sure that the C++ version of the examples (discussed above) works correctly.

  • To compile and test the Fortran examples, use the command
    make tao_testfortran >& fortran_log
  • If only the uniprocessor version of TAO has been installed (i.e., MPI has not been installed), then use the following command to run only sequential Fortran examples:
    make tao_testfortran_uni >& fortran_uni_log

TAO Fortran programs can use the suffix .F rather than the traditional suffix .f, so that the TAO header files can be easily included in Fortran programs. The Fortran chapter within the TAO users manual provides additional details regarding the Fortran interface.

Optional Packages:

TAO provides an interface to several software packages:

  • Common Component Architecture (CCA), from http://www.cca-forum.org. TAO provides an Optimization Solver component that is compatible with the CCA specifications.
  • Global Arrays (GA), from (http://www.emsl.pnl.gov/docs/global/ga.html). Users familiar with GA can use TAO with GA. Identify the location of the GA installation in the file ${TAO_DIR}/bmake/packages.${PETSC_ARCH}.

    There is a bug in TAO's interface to Global Arrays, you will need to remove the line PETSC_CCPFLAGS=... in ${TAO_DIR}/src/externaltao/globalarraytao/makefile and ${TAO_DIR}/src/externaltao/globalarraytao/examples/makefile

These packages are not developed, maintained, or supported by the TAO team; we merely provide an interface to them. To use any of these optional packages, obtain the packages prior to installing TAO and TAO needs to be configured to use them:

  1. There is a line
    #include ${TAO_DIR}/bmake/packages.${PETSC_ARCH}
    in the file ${TAO_DIR}/bmake/packages that needs to be uncommented (remove the '#').
  2. copy the file ${TAO_DIR}/bmake/packages.arch to ${TAO_DIR}/bmake/packages.${PETSC_ARCH}.
  3. edit ${TAO_DIR}/bmake/packages.${PETSC_ARCH} to set the location of the external packages.

Multiple Installations:

When building TAO for two or more machine types that share a common file system, for example solaris and hpux, multiple TAO directory trees are NOT needed. A single TAO directory can (and should) be used; TAO automatically places the libraries for each machine in a different location. In particular, the libraries for a given PETSC_ARCH are installed in the directory, ${TAO_DIR}/lib/${PETSC_ARCH}.

Shared Libraries:

TAO supports the use of shared libraries for the machines solaris, alpha, IRIX, IRIX64 and linux to enable faster linking and smaller executables. In order to enable shared libraries, PETSc must be configured with the option --with-shared.

Support:

Please let us know of any difficulties in installing and using the software. We are willing to assist with an installation if a problem remains unresolved. Our contact information is listed here