newmata.txt

科学和工程计算中使用统计功能开发工具包

//$$ newmata.txt                                   Documentation file


   Documentation for newmat06, an experimental matrix package in C++.
   ==================================================================


MATRIX PACKAGE                                           1 December, 1992

Copyright (C) 1991,2: R B Davies

Permission is granted to use but not to sell.


Contents
========

General description
Is this the package you need?
Changes
Where you can get a copy of this package
Compiler performance
Example
Detailed documentation
   Customising
   Constructors
   Elements of matrices
   Matrix copy
   Unary operators
   Binary operators
   Combination of a matrix and scalar
   Scalar functions of matrices
   Submatrix operations
   Change dimensions
   Change type
   Multiple matrix solve
   Memory management
   Output
   Accessing matrices of unspecified type
   Cholesky decomposition
   Householder triangularisation
   Singular Value Decomposition
   Eigenvalues
   Sorting
   Fast Fourier Transform
   Interface to Numerical Recipes in C
   Exceptions
   Clean up following an exception
List of files
Problem report form


---------------------------------------------------------------------------


General description
===================

The package is intented for scientists and engineers who need to
manipulate a variety of types of matrices using standard matrix
operations. Emphasis is on the kind of operations needed in statistical
calculations such as least squares, linear equation solve and
eigenvalues.

It supports matrix types

    Matrix                       (rectangular matrix)
    nricMatrix                   (variant of rectangular matrix)
    UpperTriangularMatrix
    LowerTriangularMatrix
    DiagonalMatrix
    SymmetricMatrix
    BandMatrix
    UpperBandMatrix              (upper triangular band matrix)
    LowerBandMatrix              (lower triangular band matrix)
    SymmetricBandMatrix
    RowVector                    (derived from Matrix)
    ColumnVector                 (derived from Matrix).

Only one element type (float or double) is supported.

The package includes the operations *, +, -, inverse, transpose,
conversion between types, submatrix, determinant, Cholesky
decomposition, Householder triangularisation, singular value
decomposition, eigenvalues of a symmetric matrix, sorting, fast fourier
transform, printing and an interface with "Numerical Recipes in C".

It is intended for matrices in the range 4 x 4 to the maximum size your
machine will accomodate in a single array. That is 90 x 90 (125 x 125
for triangular matrices) in machines that have 8192 doubles as the
maximum size of an array. It will work for very small matrices but
becomes rather inefficient.

A two-stage approach to evaluating matrix expressions is used to improve
efficiency and reduce use of temporary storage.

The package is designed for version 2 or 3 of C++. It works with Borland
C++ on a PC and AT&T C++ (2.1 & 3) and Gnu C++ (2.2) on a Sun. It works
with some problems with Zortech C++ (version 3).


---------------------------------------------------------------------------


Is this the package you need?
=============================

Do you

1.   need matrix operators such as * and + defined as operators so you
     can write things like

        X  = A * (B + C);

2.   need a variety of types of matrices

3.   need only one element type (float or double)

4.   work with matrices in the range 4x4 to 90x90

5.   tolerate a large package


Then maybe this is the right package for you. 

If you don't need (1) then there may be better options. Likewise if you
don't need (2) there may be better options. If you require "not (5)"
then this is not the package for you.


If you need (2) and "not (3)" and have some spare money, then maybe you
should look at M++ from Dyad or the Rogue Wave matrix package.


If you need not (4); that is very large matrices that will need to be
stored on disk, there is a package YAMP on CompuServe under the Borland
C++ library that might be of interest.


Details of some other free C or C++ matrix packages follow - extracted
from the list assembled by [e-mail].

Name: SPARSE
Where: in sparse on Netlib
Description: library for LU factorisation for large sparse matrices 
Author: Ken Kundert, Alberto Sangiovanni-Vincentelli,
     [e-mail]

Name: matrix.tar.Z
Where: in ftp-raimund/pub/src/Math on nestroy.wu-wien.ac.at
     (137.208.3.4)
Author: Paul Schmidt, TI
Description: Small matrix library, including SOR, WLS

Name: matrix04.zip
Where: in mirrors/msdos/c on wuarchive.wustl.edu
Description: Small matrix toolbox

Name: Matrix.tar.Z
Where: in pub ftp.cs.ucla.edu
Description: The C++ Matrix class, including a matrix implementation of
     the backward error propagation (backprop) algorithm for training
     multi-layer, feed-forward artificial neural networks
Author: E. Robert (Bob) Tisdale, [e-mail]

Name: meschach
Where: in c/meschach on netlib
Systems: Unix, PC
Description: a library for matrix computation; more functionality than
     Linpack; nonstandard matrices
Author: David E. Stewart, [e-mail]
Version: 1.0, Feb 1992

Name: nlmdl
Where: in pub/arg/nlmdl at ccvr1.cc.ncsu.edu (128.109.212.20)
Language: C++
Systems: Unix, MS-DOS (Turbo C++)
Description: a library for estimation of nonlinear models
Author: A. Ronald Gallant, [e-mail]
Comments: nonlinear maximisation, estimation, includes a real matrix
     class
Version: January 1991



---------------------------------------------------------------------------


Changes
=======

Newmat06 - December 1992:

Added band matrices; 'real' changed to 'Real' (to avoid potential
conflict in complex class); Inject doesn't check for no loss of
information;  fixes for AT&T C++ version 3.0; real(A) becomes
A.AsScalar(); CopyToMatrix becomes AsMatrix, etc; .c() is no longer
required (to be deleted in next version); option for version 2.1 or
later. Suffix for include files changed to .h; BOOL changed to Boolean
(BOOL doesn't work in g++ v 2.0); modfications to allow for compilers
that destroy temporaries very quickly; (Gnu users - see the section of
compiler performance). Added CleanUp, LinearEquationSolver, primitive
version of exceptions.


Newmat05 - June 1992:

For private release only 


Newmat04 - December 1991:

Fix problem with G++1.40, some extra documentation


Newmat03 - November 1991:

Col and Cols become Column and Columns. Added Sort, SVD, Jacobi,
Eigenvalues, FFT, real conversion of 1x1 matrix, "Numerical Recipes in
C" interface, output operations, various scalar functions. Improved
return from functions. Reorganised setting options in "include.hxx".


Newmat02 - July 1991:

Version with matrix row/column operations and numerous additional
functions.


Matrix - October 1990:

Early version of package.


---------------------------------------------------------------------------


How to get a copy of this package
=================================

I am putting copies on Compuserve (Borland library, zip format),
SIMTEL20 (MsDos library, zip format), comp.sources.misc on Internet
(shar format).


---------------------------------------------------------------------------


Compiler performance
====================

I have tested this package on a number of compilers. Here are the levels
of success with this package. In most cases I have chosen code that
works under all the compilers I have access to, but I have had to
include some specific work-arounds for some compilers. For the MsDos
versions, I use a 486dx computer running MsDos 5. The unix versions are
on a Sun Sparc station or a Silicon Graphics or a HP unix workstation.
Thanks to Victoria University and Industrial Research Ltd for access to
the Unix machines.

A series of #defines at the beginning of "include.h" customises the
package for the compiler you are using. Turbo, Borland, Gnu and Zortech
are recognised automatically, otherwise you have to set the appropriate
#define statement. Activate the option for version 2.1 if you are using
version 2.1 of C++ or later.

Borland C++ 3.1: Recently, this has been my main development platform,
so naturally almost everything works with this compiler. Make sure you
have the compiler option "treat enums as ints" set. There was a problem
with the library utility in version 2.0 which is now fixed. You will
need to use the large model. If you are not debugging, turn off the
options that collect debugging information.

Zortech C++ 3.0: "const" doesn't work correctly with this compiler, so
the package skips all of the statements Zortech can't handle. Zortech
leaves rubbish on the heap. I don't know whether this is my programming
error or a Zortech error or additional printer buffers. Deactivate the
option for version 2.1 in include.h. Does not support IO manipulators.
Otherwise the package mostly works, but not completely.

Glockenspiel C++ (2.00a for MsDos loading into Microsoft C 5.1): I
haven't tested the latest version of my package with Glockenspiel. I had
to #define the matrix names to shorter names to avoid ambiguities and
had quite a bit of difficulty stopping the compiles from running out of
space and not exceeding Microsoft's block nesting limit. A couple of my
test statements produced statements too complex for Microsoft, but
basically the package worked. This was my original development platform
and I still use .cxx as my file name extensions for the C++ files.

Sun AT&T C++ 2.1;3.0: This works fine. Except aggregates are not
supported in 2.1 and setjmp.h generated a warning message. Neither
compiler would compile when I set DO_FREE_CHECK (see my file
newmatc.txt).

Gnu G++ 2.2:  This mostly works. You can't use expressions like
Matrix(X*Y) in the middle of an expression and (Matrix)(X*Y) is
unreliable. If you write a function returning a matrix, you MUST use the
ReturnMatrix method described in this documentation. This is because g++
destroys temporaries occuring in an expression too soon for the two
stage way of evaluating expressions that newmat uses. Gnu 2.2 does seem
to leave some rubbish on the stack. I suspect this is a printer buffer
so it may not be a bug. There were a number of warning messages from the
compiler about my "unconstanting" constants; but I think this was just
gnu being over-sensitive.

JPI: Their second release worked on a previous version of this package
provided you disabled the smart link option - it isn't smart enough. I
haven't tested the latest version of this package.


---------------------------------------------------------------------------

Example
=======

An example is given in  example.cxx .  This gives a simple linear
regression example using four different algorithms. The correct output
is given in example.txt. The program carries out a check that no memory
is left allocated on the heap when it terminates. The file  example.mak
is a make file for compiling example.cxx under gnu g++. Use the gnu make
facility. You can probably adapt for the compiler you are using.

 ---------------------------------------------------------------------
| Don't forget to remove references to  newmat9.cxx  in the make file |
| if you are using a compiler that does not support the standard io   |
| manipulators.                                                       |
 ---------------------------------------------------------------------

---------------------------------------------------------------------------


Detailed Documentation
======================

Copyright (C) 1989,1990,1991,1992: R B Davies

Permission is granted to use but not to sell.

   --------------------------------------------------------------
  | Please understand that this is a test version; there may     |
  | still be bugs and errors. Use at your own risk. I take no    |
  | responsibility for any errors or omissions in this package   |
  | or for any misfortune that may befall you or others as a     |
  | result of its use.                                           |
   --------------------------------------------------------------

Please report bugs to me at

    [e-mail]

or

    Compuserve 72777,656

When reporting a bug please tell me which C++ compiler you are using (if
known), and what version. Also give me details of your computer (if
known). Tell me where you downloaded your version of my package from and
its version number (eg newmat03 or newmat04). (There may be very minor
differences between versions at different sites). Note any changes you
have made to my code. If at all possible give me a piece of code
illustrating the bug.

Please do report bugs to me.


The matrix inverse routine and the sort routines are adapted from
"Numerical Recipes in C" by Press, Flannery, Teukolsky, Vetterling,
published by the Cambridge University Press.

Other code is adapted from routines in "Handbook for Automatic
Computation, Vol II, Linear Algebra" by Wilkinson and Reinsch, published
by Springer Verlag. 


Customising
-----------

I use .h as the suffix of definition files and .cxx as the suffix of
C++ source files. This does not cause any problems with the compilers I
use except that Borland and Turbo need to be told to accept any suffix
as meaning a C++ file rather than a C file.

Use the large model when you are using a PC. Do not "outline" inline
functions.

Each file accessing the matrix package needs to have file newmat.h 
#included  at the beginning. Files using matrix applications (Cholesky
decomposition, Householder triangularisation etc) need newmatap.h
instead (or as well). If you need the output functions you will also
need newmatio.h.

The file  include.h  sets the options for the compiler. If you are using
a compiler different from one I have worked with you may have to set up
a new section in  include.h  appropriate for your compiler.

Borland, Turbo, Gnu and Zortech are recognised automatically. If you
using Glockenspiel on a PC, AT&T activate the appropriate statement at
the beginning of include.h.

Activate the appropriate statement to make the element type float or
double.

If you are using version 2.1 or later of C++ make sure Version21 is
#defined, otherwise make sure it is not #defined.

The file (newmat9.cxx) containing the output routines can be used only
with libraries that support the AT&T input/output routines including
manipulators. It cannot be used with Zortech or Gnu.

You will need to compile all the *.cxx files except example.cxx and the
tmt*.cxx files to to get the complete package. The tmt*.cxx files are
used for testing and example.cxx is an example. The files tmt.mak and
example.mak are "make" files for unix systems. Edit in the correct name
of compiler. This "make" file worked for me with the default "make" on
the HP unix workstation and the Sun sparc station and gmake on the
Silicon Graphics. With Borland, its pretty quick just to load all the