newmata.txt

矩阵计算库

        DOCUMENTATION FOR NEWMAT08, A MATRIX LIBRARY IN C++

Copyright (C) 1991,2,3,4,5: R B Davies

This is the "how to use" documentation for newmat. Background information on
the structure of the library is given in newmatb.txt.

This document is available as an ascii file, newmata.txt, and in hypertext
format for reading with "Mosaic". Cross-references in the ascii version are
given as section numbers.


        Introduction                                 1
        Getting started                              2
        Reference manual                             3
        Error messages                               4
        Bugs                                         5
        Files in newmat08                            6
        Problem report form                          7


        1  Introduction
        =  ============

        Conditions of use                            1.1
        Description                                  1.2
        Is this the library for you?                 1.3
        Other matrix libraries                       1.4
        Where to find this library                   1.5
        How to contact the author                    1.6
        Change history                               1.7
        References                                   1.8


        1.1  Conditions of use
        ===  ========== == ===

Copyright (C) 1991,2,3,4,5: R B Davies.

Permission is granted to use and distribute but not to sell except for costs
of distribution. Distribution as part of low cost CD-ROM collections is
welcomed.
 ------------------------------------------------------------------------------
Please understand that 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. See the problem
report form [7].

"Please do report bugs to me."



        1.2  General description
        ===  ======= ===========

The package is intended 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 *, +, -, concatenation, inverse,
transpose, conversion between types, submatrix, determinant, Cholesky
decomposition, QR 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 15 x 15 to the maximum size your
machine will accomodate in a single array. For example 90 x 90 (125 x 125 for
triangular matrices) in machines that have 8192 doubles as the maximum size of
an array. The number of elements in an array cannot exceed the maximum size of
an "int". The package 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 (3.1
& 4.0), Microsoft (7 & 8) and Watcom (10) C++ on a PC and AT&T C++ (2.1 & 3)
and Gnu G++ (2.3.3, 2.5.8 & 2.6.0). It works with some problems with Zortech
C++ (version 3.04).



        1.3  Is this the library for you?
        ===  == ==== === ======= === ====

Do you

1:  understand * to mean matrix multiply and not element by element multiply

2:  need matrix operators such as * and + defined as operators so you can
write things like

    X  = A * (B + C);

3:  need a variety of types of matrices (but not sparse)

4:  need only one element type (float or double)

5:  work with matrices in the range 10 x 10 up to what can be stored in one
block in memory

6:  tolerate a large package


Then maybe this is the right package for you. 



        1.4  Other matrix libraries
        ===  ===== ====== =========

For commercial packages that support multiple element types, look at M++ from
Dyad [phone in the USA [phone], [phone], fax [phone]], or
the Rogue Wave matrix package [[phone], [phone], fax
[phone]].

For details of other matrix packages look at the listing from Keith Briggs. A
recent version of this is in file kbriggs.txt included with this package. Also
look at Ajay Shah's list of free numerical software in C and C++. The file is
numcomp-free-c.gz in pub/C-numanal on usc.edu. Nikki Locke produces a list of
C++ libraries in general - see
pub/usenet-by-group/comp.lang.c++/c++_FAQ/libraries in rtfm.mit.edu. 

Also look on Compuserve in the forums of the various C++ compilers.



        1.5  Where to find this library
        ===  ===== == ==== ==== =======


*   Compuserve (Borland library, zip format)

*   SimTel (msdos.cpluspls directory, zip format) - see oak.oakland.edu

*   comp.sources.misc on Internet (shar format) - see wuarchive.wustl.edu




        1.6  How to contact the author
        ===  === == ======= === ======


   Robert Davies
   16 Gloucester Street
   Wilton
   Wellington
   New Zealand

   "email:" [e-mail]




        1.7  Change history
        ===  ====== =======

Newmat08 - January, 1995:

Corrections to improve compatibility with Gnu, Watcom. Concatenation of
matrices. Elementwise products. Option to use compilers supporting exceptions.
Correction to exception module to allow global declarations of matrices. Fix
problem with inverse of symmetric matrices. Fix divide-by-zero problem in SVD.
Include new QR routines. Sum function. Non-linear optimisation.
GenericMatrices.

Newmat07 - January, 1993

Minor corrections to improve compatibility with Zortech, Microsoft and Gnu.
Correction to exception module. Additional FFT functions. Some minor increases
in efficiency. Submatrices can now be used on RHS of =. Option for allowing C
type subscripts. Method for loading short lists of numbers.


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); modifications 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.



        1.8  References
        ===  ==========

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.

Many of the advanced matrix routines are adapted from routines in "Handbook
for Automatic Computation, Vol II, Linear Algebra" by Wilkinson and Reinsch,
published by Springer Verlag.



        2  Getting started
        =  ======= =======

        Overview                                     2.1
        Customising                                  2.2
        Compiler performance                         2.3
        Updating from previous versions              2.4
        Example                                      2.5
        Testing                                      2.6





        2.1  Overview
        ===  ========

I use .h as the suffix of definition files and .cpp as the suffix of C++
source files.

You will need to compile all the *.cpp files except example.cpp, the tmt*.cpp
files, sl_ex.cpp and ex_nl.cpp to get the complete package. Ideally you should
store the resulting object files as a library. The tmt*.cpp files are used for
testing [2.6], example.cpp is an example [2.5] and sl_ex.cpp and ex_nl.cpp are
examples of the non-linear [3.26] solve and optimisation routines.

I include a number of "make" files for compiling the example and the test
package. See the files section [6] for details. But with Borland and Watcom,
its pretty quick just to load all the files in the interactive environment by
pointing and clicking. My Borland "make" files are generated from the
interactive environment.

Use the large or flat model when you are using a PC. Do not "outline" inline
functions. You may need to increase the stack size.

The "make" files for the Unix compilers link a .cxx file to each .cpp file
since some of these compilers do not recognise .cpp as a legitimate extension
for a C++ file. I suggest you delete this part of the "make" file and rename
the .cpp files to something your compiler recognises.

My "make" files for Unix systems are for use with 'gmake' rather than 'make'.
Ordinary 'make' works with them on the Sun but not the Silicon Graphics or HP
machines. 

Your source files that access the newmat you will need to #include one or more
of the following files.

include.h:
   if you want to access just the compiler options

newmat.h:
   to access just the main matrix library (includes include.h)

newmatap.h:
   to access the advanced matrix routines such as Cholesky decomposition, QR
triangularisation etc (includes newmat.h)

newmatio.h:
   to access the output routines (includes newmat.h) You can use this only
with compilers that support the standard input/output routines including
manipulators. It cannot be used with Zortech or early versions of Gnu.

newmatnl.h:
   to access the non-linear optimisation routines (includes newmat.h)



See the section on customising [2.2] to see how to edit include.h for your
environment and the section on compilers [2.3] for any special problems with
the compiler you are using.




        2.2  Customising
        ===  ===========

The file  include.h  sets a variety of options including several compiler