------------------------------
ANNOUNCING:  Octave ALPHA test
------------------------------

What is Octave?
---------------

Octave is a high-level language, primarily intended for numerical
computations.  It provides a convenient command line interface for
solving linear and nonlinear problems numerically.

Octave can do arithmetic for real and complex scalars and matrices,
solve sets of nonlinear algebraic equations, integrate functions over
finite and infinite intervals, and integrate systems of ordinary
differential and differential-algebraic equations.

Octave uses the GNU readline library to handle reading and editing
input.  By default, the line editing commands are similar to the
cursor movement commands used by GNU Emacs, and a vi-style line
editing interface is also available.  At the end of each session, the
command history is saved, so that commands entered during previous
sessions are not lost.

Some help is available at the Octave prompt, and there is a rough man
page.  Texinfo documentation is planned.

Two and three dimensional plotting is fully supported using gnuplot.

The underlying numerical solvers are currently standard Fortran ones
like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library
of C++ classes.  If possible, the Fortran subroutines are compiled
with the system's Fortran compiler, and called directly from the C++
functions.  If that's not possible, you can still compile Octave if
you have the free Fortran to C translator f2c.

Octave is also free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation.

Instructions for obtaining Octave are given below.

Using Octave
------------

This set of examples is by no means complete.

* to enter and compute the SVD of a matrix:

  bash$ octave
  Octave, version 0.61.  Copyright (C) 1992, John W. Eaton.
  This is free software with ABSOLUTELY NO WARRANTY.
  For details, type `warranty'.

  octave:1> a = [ 1, 2, 3 ; 4, 5, 6 ]
  a =

   1 2 3
   4 5 6

  octave:2> svd (a)
  ans =

   9.50803
   0.77287

* to also get the left and right singular matrices:

  octave:3> [u, s, v] = svd (a)
  u =

   -0.386318 -0.922366
   -0.922366 0.386318

  s =

   9.50803 0 0
   0 0.77287 0

  v =

   -0.428667 0.805964 0.408248
   -0.566307 0.112382 -0.816497
   -0.703947 -0.581199 0.408248

* to check the result:

  octave:4> u*s*v'
  ans =

   1 2 3
   4 5 6

* to define a nonlinear function and evaluate it:

  octave:5> function y = f (x)
    y(1) = x(1)^2 + x(2) - 4;
    y(2) = x(1)^2 - x(2) - 1.5;
  endfunction
  octave:6> f ([1,2])
  ans =

   -1
   -2.5

* solve it from a specified initial condition:

  octave:7> fsolve ('f', [1,2])
  ans =

   1.65831
   1.25

* to solve a set of differential equations (ending a statement with a
  semicolon suppresses the default output): 

  octave:8> function xdot = f (x, t)
    xdot = zeros (3, 1);
    xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) - 8.375e-06*x(1)^2);
    xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27;
    xdot(3) = 0.161*(x(1) - x(3));
  endfunction
  octave:9> output_times = [0, logspace(-1,2.4), logspace(2.4,2.69896)];
  octave:10> y = lsode ('f', [4; 1.1; 4], output_times);
  octave:11> y
  y =

   4 1.1 4
   7.84248 1.09504 4.03433
   8.28731 1.09372 4.04557
   8.75881 1.09205 4.06021
   9.25679 1.08994 4.07918
   9.78408 1.08727 4.10366
   10.3492 1.08391 4.13511
   10.97 1.0797 4.17546
   ... and so on ...

* and save the output in a text file:

  octave:12> save foo.out y


Octave can also be used to solve nonlinear optimization problems, but
for now this is only possible if you have a copy of Gill and Murray's
NPSOL (we can't redistribute it because it's not free software).

If you don't have NPSOL but you still want to be able to solve NLPs,
you'll need to find a replacement or order NPSOL from Stanford.

You can get more information about NPSOL from

     Stanford University
     Office of Technology Licensing
     857 Serra Street
     Stanford CA 94305-6225
     Tel: (415) 723-0651
     Fax: (415) 725-7295

Octave may soon contain support for FSQP, an NLP solver from Andre
Tits (andre@src.umd.edu) of the University of Maryland.  FSQP is not
really free software either -- it can't be redistributed to third
parties, so we can't distribute it -- but it is available free of
charge to academic sites.  Complete instructions for obtaining FSQP
will be added to Octave's documentation if support for FSQP is added.

Where to get Octave
-------------------

If you are on the Internet, you can copy the latest distribution
version of Octave from the file /pub/octave/octave-M.N.tar.Z, on
the host ftp.che.utexas.edu.  This is a compressed tar file, so be
sure to use binary mode for the transfer.  M and N stand for version
numbers; look at a listing of the directory through ftp to see what
version is available.  After you unpack the distribution, be sure to
look at the files README and INSTALL.

Installation
------------

Octave requires approximately 25MB of disk storage to unpack and
install (significantly less if you don't compile with debugging
symbols).  In order to build Octave, you will need a current version
of g++, libg++, and GNU make.  If you don't have these tools, you can
get them from many anonymous ftp archives, including ftp.che.utexas.edu,
ftp.uu.net, prep.ai.mit.edu, and wuarchive.wustl.edu, or by writing to
the FSF at 675 Mass Ave, Cambridge, MA 02139, USA.

Octave has been compiled and tested with g++-2.3.3 and libg++-2.3 on a
SPARCstation 2 running SunOS 4.1.2, an IBM RS/6000 running AIX 3.2,
a DECstation 5000/240 running Ultrix 4.2a, and an i486 system running
Linux SLS 0.99-47.  We have reports of it running on HP 9000/700
series systems running HP-UX 8.x, SGI systems running Irix 4.04, and
NeXT systems.

Implementation
--------------

Octave is being developed with GNU make, bison (a replacement for
YACC), flex (a replacement for lex), gcc/g++, and libg++ on Sun
SPARCstations, DEC DECstations, and IBM RS/6000s. It should be
easy to port it to any machine that runs gcc/g++.

The underlying numerical solvers are currently standard Fortran ones
like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library
of C++ classes (see the files in the libcruft and liboctave
subdirectories).  If possible, the Fortran subroutines are compiled
with the system's Fortran compiler, and called directly from the C++
functions.  If that's not possible, they are translated with f2c and
compiled with a C compiler.  Better performance is usually achieved if
the intermediate translation to C is avoided.

The library of C++ classes may also be useful by itself, and they are
distributed under the same terms as Octave.

Acknowledgements
----------------

Special thanks to the following people and organizations for
supporting the development of Octave:

  * Digital Equipment Corporation, for a one year grant as part of
    their External Research Program.

  * Sun Microsystems, Inc., for an Academic Equipment grant.

  * The University of Texas College of Engineering, for providing a
    Challenge for Excellence Research Supplement, and for providing an
    Academic Development Funds grant.

  * Texaco Chemical Company, for providing funding to continue the
    development of this software.

  * Noel Bell, Senior Engineer, Texaco Chemical Company, Austin Texas.

  * James B. Rawlings, Associate Professor, Department of Chemical
    Engineering, The University of Texas at Austin.

Bugs
----

Please report any problems you have to

  bug-octave@che.utexas.edu


Your bug reports play an essential role in making Octave reliable.

Reporting a bug may help you by bringing a solution to your problem,
or it may not.  In any case, the principal function of a bug report
is to help the entire community by making the next version of Octave
work better.  Bug reports are your contribution to the maintenance of
Octave.

The file BUGS in the top level directory of the source distribution
contains more information about how to provide useful bug reports.

Comments and suggestions are also always welcome.

--
John W. Eaton
jwe@che.utexas.edu
Department of Chemical Engineering
The University of Texas at Austin
