Meschach Library
			       Version 1.2b


			     David E. Stewart
			(david.stewart@anu.edu.au)

				    and

			       Zbigniew Leyk
			(zbigniew.leyk@anu.edu.au)

		      School of Mathematical Sciences
		      Australian National University
			     Canberra ACT 0200
				 Australia


		      [last revised: 6th April, 1994]


			      1. INTRODUCTION

   The Meschach Library is a numerical library of C routines for performing
calculations on matrices and vectors. It is intended for solving systems of
linear equations (dense and sparse), solve least squares problems,
computing eigenvalues and eigenvectors, etc. We do not claim that it
contains every useful algorithm in numerical linear algebra, but it does
provide a basis on which more advanced algorithms can be built. The library
is for people who know something about the C programming language,
something of how to solve the numerical problem they are faced with but do
not want to have the hassle of building all the necessary routines from the
scratch. The library is not a loose collection of numerical routines but it
comprises a coherent system. The current version is enhanced with many
features comparing with previous versions. Since the memory requirements
are nontrivial for large problems we have paid more attention to
allocation/deallocation of memory.

   The source code is available to be perused, used and passed on without
cost, while ensuring that the quality of the software is not compromised.
The software is copyrighted; however, the copyright agreement follows in
the footsteps of the Free Software Foundation in preventing abuse that
occurs with totally public domain software.

   Detailed instructions for installing Meschach are contained below.

   Pronunciation: if in doubt, say "me-shark".  This is close enough.
Don't ask us "Why call it that?"  Have a look at the quote at the front of
the manual.


			      2. AVAILABILITY

    The authors make this code openly available to others, in the hope that
it will prove to be a useful tool.  We ask only that:

* If you publish results obtained using Meschach, please consider
  acknowledging the source of the code.

* If you discover any errors in the code, please promptly communicate them
  to the authors.

    We also suggest that you send email to the authors identifying yourself
as a user of Meschach; this will enable the authors to notify you of any
corrections/improvements in Meschach.



			     3. HOW TO GET IT

   There are several different forms in which you might receive Meschach.
To provide a shorthand for describing collections of files, the Unix
convention of putting alternative letters in [...] will be used.  (So,
fred[123] means the collection fred1, fred2 and fred3.)  Meschach is
available over Internet/AARnet via netlib, or at the anonymous ftp site
thrain.anu.edu.au in the directory pub/meschach.  There are five .shar
files: meschach[01234].shar (which contain the library itself),
meschach0.shar (which contains basic documentation and machine dependent
files for a number of machines).  Of the meschach[1234].shar files, only
meschach[12].shar are needed for the basic Meschach library; the third
.shar file contains the sparse matrix routines, and the the fourth contains
the routines for complex numbers, vectors and matrices.  There is also a
README file that you should get from meschach0.shar.

   If you need the old iterative routines, the file oldmeschach.shar
contains the files conjgrad.c, arnoldi.c and lanczos.c.

   To get the library from netlib,

mail netlib@research.att.com
send all from c/meschach

   There are a number of other netlib sites which mirror the main netlib
sites.  These include netlib@ornl.gov (Oak Ridge, TN, USA), netlib@nac.no
(Oslo, Norway), ftp.cs.uow.edu.au (Wollongong, Australia; ftp only),
netlib@nchc.edu.tw (Taiwan), elib.zib-berlin.de (Berlin, Germany; ftp
only).  (For anonymous ftp sites the directory containing the Meschach
.shar files is pub/netlib/c/meschach or similar, possibly depending on the
site.)

   Meschach is available in other forms on thrain.anu.edu.au by ftp in the
directory pub/meschach.  It is available as a .tar file (mesch12a.tar for
version 1.2a), or as a collection of .shar files, or as a .zip file.  The
.tar and .zip versions each contain the entire contents of the Meschach
library.

   There is a manual called "Meschach: Matrix Computations in C" which has
been published by

	Centre for Mathematics and its Applications
	School of Mathematical Sciences
	Australian National University
	Canberra, ACT 0200
	Australia

and costs A$30 (about US$22) + postage/handling.  You can order it by
writing there or you can send email messages to one of us
(david.stewart@anu.edu.au or zbigniew.leyk@anu.edu.au) and we can pass it
on.

   If you don't have any money, as a stop gap you can get the **OLD**
manual, although it is out of date, by anonymous ftp from

	thrain.anu.edu.au : /pub/meschach/version1.1b/bookdvi.tar [.Z or .gz]

In addition, don't forget that the distribution includes a DOC directory
which contains tutorial.txt and fnindex.txt which are respectively, the
tutorial chapter (text version) and the function index (text version).



			      4. INSTALLATION

			    a) On Unix machines

   To extract the files from the .shar files, put them all into a suitable
directory and use

  sh <file>.shar

to expand the files.  (Use one sh command per file; sh *.shar will not work
in general.)

   For the .tar file, use

  tar xvf mesch12a.tar

and for the .zip file use

  unzip mesch12a.zip

   On a Unix system you can use the configure script to set up the
machine-dependent files.  The script takes a number of options which are
used for installing different subsets of the full Meschach.  For the basic
system, which requires only meschach[012].shar, use

  configure
  make basic
  make clean

   For including sparse operations, which requires meschach[0123].shar, use

  configure --with-sparse
  make sparse
  make clean

  For including complex operations, which requires meschach[0124].shar, use

  configure --with-complex
  make complex
  make clean

   For including everything, which requires meschach[01234].shar, use

  configure --with-all
  make all
  make clean

  To compile the complete library in single precision (with Real equivalent
to float), add the --with-float option to configure, use

  configure --with-all --with-float
  make all
  make clean


   Some Unix-like systems may have some problems with this due to bugs or
incompatibilities in various parts of the system.  To check this use make
torture and run torture.  In this case use the machine-dependent files from
the machines directory.  (This is the case for RS/6000 machines, the -O
switch results in failure of a routine in schur.c.  Compiling without the
-O switch results in correct results.)

   If you have problems using configure, or you use a non-Unix system,
check the MACHINES directory (generated by meschach0.shar) for your
machine, operating system and/or compiler.  Save the machine dependent
files makefile, machine.c and machine.h.  Copy those files from the
directory for your machine to the directory where the source code is.

   To link into a program prog.c, compile it using

  cc -o prog_name prog.c ....(source files).... meschach.a -lm


   This code has been mostly developed on the University of Queensland,
Australia's Pyramid 9810 running BSD4.3.  Initial development was on a
Zilog Zeus Z8000 machine running Zeus, a Unix workalike operating system.
Versions have also been successfully used on various Unix machines
including Sun 3's, IBM RT's, SPARC's and an IBM RS/6000 running AIX.  It
has also been compiled on an IBM AT clone using Quick C.  It has been
designed to compile under either Kernighan and Richie, (Edition 1) C and
under ANSI C.  (And, indeed, it has been compiled in both ANSI C and
non-ANSI C environments.)


			  b) On non-Unix machines

   First look in the machines directory for your system type.  If it is
there, then copy the machine dependent files machine.h, makefile (and
possibly machine.c) to the Meschach directory.

   If your machine type is not there, then you will need to either compile
``by hand'', or construct your own makefile and possibly machine.h as well.
The machine-dependent files for various systems should be used as a
starting point, and the ``vanilla'' version of machine.h should be used.