This package is a (limited) Python interface to the Toolkit for
Advanced Optimization (TAO) [http://www-fp.mcs.anl.gov/tao/].

REQUIREMENTS
------------

- Built TAO (1.6) and PETSc (2.2.0) libraries (see
  http://people.csail.mit.edu/~jrennie/tao/install.html for sample
  instructions).  Note that PETSc must be built with a C++ compiler (the
  Debian Sarge package won't do).
- BLAS (3.0.3), LAPACK (3.0.3) libraries
- Python (2.2+)
- C++ compiler (GNU 3.3.2)

Versions are indicated in parenthesis.  Other versions may also work.


INSTALLATION
------------

- Edit 'tao_dir' and 'petsc_dir' in config.py to indicate the correct
  locations of TAO and PETSc.  Set 'BOPT' and 'PETSC_ARCH' to the same
  values that were used to build TAO and PETSc.

- Run 'python setup.py install' to build and install the pytao module to the
  standard location.  To install to a custom location, use the --prefix and
  --exec-prefix options.  For example:

    python setup.py install --prefix=~/usr --exec-prefix=~/usr/linux

- If you install to a custom location, make sure that you have the
  PYTHONPATH environment variable set appropriately.  For example,
  include a line like this in your ~/.bash_profile:

    export PYTHONPATH=$PYTHONPATH:/home/jrennie/usr/lib/python2.3/site-packages:/home/jrennie/usr/linux/lib/python2.3

- After installation, you can use the test suite to ensure a proper
  installation and make sure that you have your PYTHONPATH set
  properly:

    python test/test_pytao.py


BASIC USAGE
-----------

Unconstrained template:

-----8<-----
#!/usr/bin/env python
import pytao
def ogfun(x):
    fobj = 0.0
    g = [0.0]*len(x)
    # calculate objective (fobj) and gradient (g)
    return (fobj,g)
x = [0.0]*10
xopt = pytao.optimize(x,ogfun)
----->8-----

Bound constrained template:

-----8<-----
#!/usr/bin/env python
import pytao
def ogfun(x):
    fobj = 0.0
    g = [0.0]*len(x)
    # calculate objective (fobj) and gradient (g)
    return (fobj,g)
x = [0.0]*10
xopt = pytao.optimize(x=x,ogfun=ogfun,xub=[1.0]*10,xlb=[-1.0]*10,
                      solver='tao_blmvm')
----->8-----

Documentation:

>>> import pytao
>>> help(pytao)


LIMITATIONS
-----------

- No multi-processor support
- Does not support solvers that require Hessian information
- Only supported "vector" type is python list
- No support for Numeric vectors

NOTES
-----

This module is raw and is not yet well-tested.  There are likely to be
bugs and there is certainly much room for improvement.  Please e-mail
information about any bugs you find.  Also I'd be very happy to apply
patches you write that would improve the module.

The line search that TAO uses does not deal well with objective
functions that go to infinity at some non-infinite value.  You may
need to reparameterize your objective in such cases.  Also, you should
contrain returned values within the range [-1e20,1e20] else TAO may
become confused.  

A run that yields "failure" may still produce a good result.  The line
search tends to get stuck on numerically difficult problems, but I've
found that it often ends up sufficiently close to the solution.

Jason Rennie
jrennie@csail.mit.edu
