$Id:$

This is the tentative NLPy FAQ.
It will be enriched as NLPy is, and will be structured into sections.

Q: What is NLPy?

A: NLPy is a collection of tools and interfaces for optimization algorithm
   implementation and prototyping.  It is a set of Python modules and classes
   used to support sparse matrices, nonlinear optimization methods and the
   efficient solution of large sparse linear systems, especially those occuring
   in the course of optimization algorithms (e.g. symmetric indefinite
   systems).

Q: What does "NLPy" mean?
A: NLP stands for "nonlinear programming" which is often regarded as synonymous
   to "nonlinear optimization", referring to solving problems of the form

         minimize    f(x)
         subject to  cL <= c(x) <= cU
                     h(x) = 0
                     xL <= x <= xU

   where the function f is real valued and c, and h are vector-valued
   constraint functions. The quantities cL, cU, xL and xU are vectors of
   appropriate dimensions.

   The final 'y' in "NLPy" is the traditional 'y' appearing in the name of
   Python packages. It reminds users that this is a Python project.

Q: How do you pronounce "NLPy"?
A: It is pronounced N-L-Pie.

Q: Is NLPy like Matlab?
A: NLPy differs from Matlab in its purpose and its origin.  Some might argue
   that Python, like Matlab, is an interpreted language. We feel however that
   it has a number of advantages for scientific computing. First, it is open
   source and no-one will deny today that the Python language is omnipresent in
   universities, schools, laboratories and homes. Second, it is object
   oriented, which turns out to be perfectly suited to the implementation of
   numerical algorithms. Third, just like Matlab, Python is easily extended
   using the C language.  However, interactions between Python and C only
   involve pointers and no explicit exchange of data beyond them.  This allows
   significant speedups. NLPy and Matlab also serve different purposes, as
   explained in the answer to the next question.

Q: What is the purpose of NLPy?
A: The purpose of NLPy is to offer an environment in which implementing,
   testing, prototyping, experimenting with, modifying and creating innovative
   optimization algorithms targeted at large-scale constrained problems is a
   moderately easy task. We feel that the environment should be useful, simple
   and intuitive enough that programmers need only concentrate on the logic of
   the algorithm instead of the intricacies of the programming language. We
   believe that NLPy is appropriate for teaching, for learning, and also for
   bleeding edge research in large-scale numerical optimization. This is
   achieved by providing the heavy-duty number-crunching procedures in fast,
   low-level languages such as C, Fortran 77 or Fortran 90/95, which are among
   the most popular languages in scientific computing.

   The goals of NLPy are _NOT_ to

   o provide an integrated interactive development environment for general
     scientific applications. This is already available in, e.g., the
     high-quality SciPy package,

   o provide general-purpose univariate optimization heuristics such as the
     bisection method or the simulated annealing.  Again, such procedures may be
     found in SciPy.

   Instead, NLPy aims to

   o represent the bleeding edge of research in numerical (differentiable or
     not) optimization,

   o provide a number of low-level tools upon which algorithms may be built,
     with the intent of solving potentially large problems,

   o use sparse matrix data structures to do so,

   o provide tools that are useful in the assessment of the performance of
     optimization algorithms.

Q: Is NLPy compatible with SciPy?
A: To some extent. We are not exactly sure how compatible it is exactly, but
   let us mention a few points in this regard.
   
   SciPy has a large number of interfaces to LAPACK routines, which NLPy does
   not. The reason why is not to duplicate work that has already been done, and
   done well.
   
   SciPy also has interfaces to packages which use sparse matrices (e.g,
   SPARSKIT and SuperLU). However, NLPy relies on PySparse for its sparse
   matrix operations. We are not excluding to work towards compatibility with
   SciPy in the future---such work would in fact be a great step ahead.

   Both SciPy and NLPy use NumPy arrays.

   Even in the current state of things, it should not be difficult to exchange
   data between SciPy and NLPy.

   SciPy has its own plotting module called Chaco. NLPy is using Matplotlib
   because we believe that it is a very high-quality, very professionally
   written and maintained package, that has the great advantage of being easy
   to use both for new users and for users coming from Matlab. It will satisfy
   both those who only want to be able to type 'plot( sin(x) )' and those who
   prefer to use a more object-oriented programming style.

   Finally, SciPy also features modules for other areas of applied mathematics
   and engineering.

Q: Is NLPy Open Source?
A: Yes. NLPy is released under the GLPL, the GNU Lesser Public License. For the
   time being, NLPy relies on packages which are not Open Source. It is
   important to realize that NLPy relies on one piece of proprietary software;
   the AMPL modeling language for optimization. It is possible to download a
   copy of the student version of AMPL from www.ampl.com free of charge.

Q: How can I find out more about NLPy?
A: Check the website regularly. You may also e-mail the authors for
   information. It is our intention to set up a mailing list and attend to
   users' requests and questions. We are asking users to be understanding
   however and we are very busy with our research and teaching commitments. We
   will do all we can to best answer questions, help users, consider
   suggestions, accept contributions, etc, etc.

Q: Do I need NumPy?
A: Yes. Recent versions of NLPy are based on the new and improved NumPy, which
   supersedes the older Numeric extension.

Q: Can I use NLPy with ATLAS?
A: Yes. In your ~/.nlpy, set the variable LIBBLAS_LOC to
     -lf77blas -lcblas -latlas
   where libf77blas.a, libcblas.a and libatlas.a were created when you
   installed ATLAS. Note: The order of the libraries is important. You may have
   to add a search path as in -L/my/own/lib -lf77blas -lcblas -latlas.

Q: Can I use NLPy with the GOTO BLAS?
A: Yes. In your ~/.nlpy, set the variable LIBBLAS_LOC to
     -lgoto -lpthread
   making sure that libgoto.so was compiled with the same compiler as NLPy. You
   may have add a search path as in -L/my/own/lib -lgoto -lpthread.

Q: How can I be sure of which BLAS I am using?
A: After compilation of NLPy, change to the Lib directory and say
   'ldd libma27.so'. If you used shared BLAS libraries, they should appear in
   the list.
