TAO

Documentation: Installation

This documentation is valid for TAO version 2.2.2, for the latest version, please visit the PETSc documentation page at http://www.mcs.anl.gov/petsc/documentation/installation.html.

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

  • Linux
  • Apple OS X
  • Windows (under cygwin)
  • freebsd
  • Solaris
  • Cray

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
    • (if no Microsoft, Intel, or Borland C++ compiler available)

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 (2.2.0) requires version 3.4.x of PETSc. Do NOT configure PETSc with complex arithmetic (--with-scalar-type=complex)
Other useful PETSc options are:
  • --with-shared-libraries creates shared libraries
  • --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-f2cblaslapack 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.4.0
      (export PETSC_DIR=/home/username/petsc-3.4.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-2.2.0.tar.gz | tar -xvf -
    By default, this will create a directory called tao-2.2.0 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-2.2.0
    (export TAO_DIR=/home/username/tao-2.2.0 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. Note that there will probably be some small numerical differences because of the architecture, compiler, or blas/lapack libraries. If there are any errors, please let us know what they were (and any solutions you may have found). 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
    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.

Multiple Installations:

When building TAO for two or more configurations, such as one for debugging and one for optimized libraries, or for machine types that share a common file system, 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}/${PETSC_ARCH}/lib.

Shared Libraries:

TAO supports the use of shared libraries on supported architectures to enable faster linking and smaller executables. In order to enable shared libraries, PETSc must be configured with the option --with-shared-libraries.

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