TAO Installation Guide for UNIX Systems

Welcome to TAO. Please let us know of any difficulties in installing and using the software.  We are always willing to assist with an installation if a problem remains unresolved. Installing TAO should take less than an hour. If installation is taking longer, please refer to bug-reporting information. We will help with installation problems on any of the supported architectures.

TAO requires a minimum of 60 Mbytes of disk space to install for a single operating system.  TAO must be compiled with a C++ compiler.  

Required Software:

Prior to installing TAO, the machine must have:

• An implementation of MPI. Parallel machines now come with one provided by the vendors (e.g., IBM SP, Cray T3E, and SGI machines); check with your support staff. We recommend using the vendor-provided implementation of MPI if it has been installed, since this usually provides better performance than the freeware versions. Otherwise, we recommend MPICH, which is available at http://www.mcs.anl.gov/mpi/mpich. If MPI is not yet installed on your system, retrieve a version of MPI, install it, and run the example programs before proceeding further. 

  For users who are interested ONLY in running TAO sequentially, we have included a stripped-down version of MPI that allows TAO to be compiled without installing an external version of MPI. This setup allows the user to run ONLY uniprocessor TAO programs, not parallel ones.

• A copy of the PETSc software, 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 requires version 2.2.0 of PETSc, compiled with a C++ compiler (i.e., using BOPT=[g_c++,O_c++]). If this software is not yet installed on your system, retrieve it and run the example programs before proceeding further.

Optional Packages:

TAO provides an interface to several software packages.. 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 following prior to installing TAO:

• The ALICE Memory Snooper (AMS), from http://www.mcs.anl.gov/ams.   This package allows one to monitor (and change) variables in running TAO programs (or, more generally, any programs using MPI). 
• Global Arrays (GA), from (http://www.emsl.pnl.gov:2080/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.

Installing TAO:

• The TAO distribution can be unbundled with
     gunzip -c tao-1.6.tar.gz | tar -xvf -
  By default, this will create a directory called tao-1.4 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.6
  Users may want to set this variable in their .cshrc file, for example.
• Since TAO interfaces to PETSc for portable makefiles and parallel linear algebra support, you must also:
  • Set the environmental variable PETSC_DIR to the full path of the PETSc home directory, for example,
       setenv PETSC_DIR /home/username/petsc-2.2.0
  • Set the environmental variable PETSC_ARCH, which indicates the architecture on which both TAO and PETSc will be configured. For example, use
       setenv PETSC_ARCH  `$PETSC_DIR/bin/petscarch`
    This utility should set the environmental variable correctly even of several machines of different types are on the same file system.

  Assuming that PETSc has already been correctly installed, simply setting these environmental variables is all that is needed for TAO installation to begin.

• If external packages, other than PETSc, are being used with TAO, edit the file ${TAO_DIR}/bmake/packages to define the location of these packages.

• In the TAO home directory, type
     make BOPT=g_c++ all
  to build a debugging version of TAO or
     make BOPT=O_c++ all
  to build optimized version of the TAO libraries. The flag BOPT determines what type of libraries are built (i.e., specifies compiler options). 

• 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 BOPT=g_c++ all >& makeg.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 BOPT=g_c++ 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 BOPT=g_c++ 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 BOPT=g_c++ minsurf1
     make runminsurf1 (or, for example, mpirun minsurf1)
  This alternative may be preferable if "make BOPT=g_c++ 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 BOPT=g_c++ 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 BOPT=g_c++ 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 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 BOPT and PETSC_ARCH are installed in the directory, ${TAO_DIR}/lib/lib${BOPT}/${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.  These libraries are built automatically during installation. In addition, TAO now defaults to using these libraries as dynamic libraries on these machines. For most users this does not matter.