newmata.txt

矩阵计算库

dependent options. You may need to edit include.h to get the options you
require. 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, Microsoft, Watcom and Zortech are recognised
automatically. If none of these are recognised a default set of options is
used. These are fine for AT&T, HPUX and Sun C++. If you using a compiler I
don't know about you may have to write a new set of options.

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

If you are using the standard style for deleting arrays (AT&T version 2.1 or
later) make sure Version21 is #defined. If you are using the old style, make
sure it is not #defined.

There is an option in include.h for selecting whether you use compiler
supported exceptions, simulated exceptions, or disable exceptions. Use the
option for compiler supported exceptions if and only if you have set the
option on your compiler to recognise exceptions. Disabling exceptions
sometimes helps with compilers that are incompatible with my exception
simulation scheme.

I suggest you leave the option TEMPS_DESTROYED_QUICKLY activated, even though
the Gnu compiler is the only one I know about that requires it. This stores
the "trees" dsecribing matrix expressions on the heap rather than the stack
and, surprisingly, seems to give better performance. See the discussion in
newmatb.txt for more explanation.

Leave the option TEMPS_DESTROYED_QUICKLY_R not activated unless you are using
the Gnu G++ [2.3.3] compiler. This option controls whether the ReturnMatrix
[3.13] construct uses the stack or the heap. The heap version is rather kludgy
and probably should be avoided where possible.

The option DO_FREE_CHECK is used for tracking memory leaks and normally should
not be activated.

Activate SETUP_C_SUBSCRIPTS if you want to use traditional C style element
access [3.2]. 




        2.3  Compiler performance
        ===  ======== ===========

I have tested this library on a number of compilers. Here are the levels of
success and any special considerations. 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 6 or windows NT. 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.

I have set up a block of code for each of the compilers in include.h. Turbo,
Borland, Gnu, Zortech, Microsoft and Watcom are recognised automatically.
There is a default option that works for AT&T, Sun C++ 4.0.1 and HPUX. So you
don't have to make any changes for these compilers. Otherwise you may have to
build your own set of options in include.h.

        AT&T                                         2.3.1
        Borland                                      2.3.2
        Gnu G++                                      2.3.3
        HPUX                                         2.3.4
        Microsoft                                    2.3.5
        Sun                                          2.3.6
        Watcom                                       2.3.7
        Zortech                                      2.3.8




        2.3.1  AT&T
        =====  ====

AT&T C++ 2.1;3.0.1 on a Sun: It works fine with 3.0.1. I haven't been able to
test the latest version of the library on 2.1. The previous version worked
fine. Except aggregates are not supported in 2.1 and setjmp.h generated a
warning message. If you are using "interviews" you may get a conflict with
Catch. Either #undefine Catch or replace Catch with CATCH throughout my
package. In AT&T 2.1 you may get an error when you use an expression for the
single argument when constructing a Vector or DiagonalMatrix or one of the
Triangular Matrices. You need to evaluate the expression separately.

You cannot run my non-linear [3.26] package with these compilers, because of
my use of labels.



        2.3.2  Borland
        =====  =======

Borland C++ 3.1, 4.5: Recently this has been my main development platform, so
naturally everything works with this compiler. 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. Make sure you don't run Borland's exceptions and my
simulated exceptions at the same time.

When running my test program with Borland 4.5 under ms-dos you may run out of
memory. Either compile the test routine to run under "easywin" or use
simulated exceptions rather than the built in exceptions. Under "easywin" the
test program indicates a memory leak. I presume this is partly because of the
way windows organises its heap rather than there being a real problem.

However there does seem to be genuine memory problem when you use the built-in
exceptions. Under "easywin" the automatic clean-up of objects by the exception
mechanism does not seem to work. Use my simulated exceptions if this is a
problem.



        2.3.3  Gnu G++
        =====  === ===

Gnu G++ 2.3.3, 2.5.8:  These mostly work. You must enable the options
TEMPS_DESTROYED_QUICKLY and TEMPS_DESTROYED_QUICKLY_R. 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 [3.13] 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 seems to leave some
rubbish on the stack. Possibly this is a printer buffer so it may not be a
bug. You will have problems with versions of Gnu earlier than 2.3.1.

Linux: Gnu G++ 2.5.8 seems a little more touchy than regular G++. But
basically the package works.

Gnu G++ 2.6.0: Seems OK. There should be better compatibility because version
2.6 retains temporaries until the end of the statement instead of destroying
them immediately following the first access. I suggest you enable option
TEMPS_DESTROYED_QUICKLY but not TEMPS_DESTROYED_QUICKLY_R.



        2.3.4  HP-UX
        =====  =====

HP 9000 series HP-UX. I have tried the library on two versions of HP-UX. (I
don't know the version numbers, the older is a clone of AT&T 3, the newer is
HP's version with exceptions). Both worked after the modifications described
in this section except that I couldn't compile the non-linear [3.26] package
due to my use of labels.

With the older version of the compiler I needed to edit the math.h library
file to remove a duplicate definition of abs.

With the newer version you can set the +eh option to enable exceptions and
activate the UseExceptions option in include.h. If you are using my make file,
you will need to replace CC with CC +eh where ever CC occurs. I recommend that
you do not do this and either disable exceptions or use my simulated
exceptions. I get core dumps when I use the built-in exceptions and suspect
they are not sufficiently debugged as yet.

If you are using my simulated exceptions you may get a mass of error messages
from the linker about __EH_JMPBUF_TEMP. In this case get file setjmp.h (in
directory /usr/include/CC ?) and put extern in front of the line

   jmp_buf * __EH_JMPBUF_TEMP;

The file setjmp.h is accessed in my file myexcept.h. You may want to change
the #include statement to access your edited copy of setjmp.h.



        2.3.5  Microsoft
        =====  =========

Microsoft C++ (7.0, 8.0): Seems to work OK. You must #define
TEMPS_DESTROYED_QUICKLY owing to a bug in version 7 (at least) of MSC. There
are some notes in the file include.h on changes to run under version 7. I
haven't tried the latest version of newmat08 on version 7.

Haven't tried visual C++ yet.




        2.3.6  Sun
        =====  ===

Sun C++ (version 4.0.1): This generally works fine. However, I suspect that
there is a problem with my non-linear [3.26] package, even though the program
appears to run correctly, probably because of my use of labels. When I set
DO_FREE_CHECK, I detect non-existent objects being deleted and the program
fails if I use simulated exceptions.



        2.3.7  Watcom
        =====  ======

Watcom C++ (version 10): basically this works fine. Don't try to run Watcom's
exceptions and my simulated exceptions at the same time.

There does seem to be a problem with expressions such as

   X = Matrix(A+B)+C;

Occasionally the temporary object created by Matrix(A+B) is destroyed twice.
In most cases this does not seem to cause a problem. However, I think one
should avoid code such as this - in fact, there is generally not much point to
such code. Alternatively use my simulated exceptions as the problem seems to
occur only with the built in exceptions enabled. 



        2.3.8  Zortech
        =====  =======

Zortech C++ 3.04: "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. Best don't #define TEMPS_DESTROYED_QUICKLY.
Exceptions and the nric interface don't work. I think some of the problems are
because Zortech doesn't handle conversions correctly, particularly automatic
conversions. But, also newmat is just too big for my version of Zortech.
Zortech runs much more slowly than Borland and Microsoft. Use the large model
and compile as much as possible with optimisation on to save space. You won't
be able to get the whole test program to work. Zortech doesn't have
io-manipulators so you can't compile the example.

I haven't tried the Symantec successors to Zortech.





        2.4  Updating newmat08
        ===  ======== ========

        Updating from previous 08 betas               2.4.1
        Updating from previous versions               2.4.2


        2.4.1  Updating from previous 08 betas
        =====  ======== ==== ======== == =====


If you were using the non-linear optimisation routine in an previous beta,
note that rowvectors and columnvectors have been swapped in this version of
newmatnl. You now derive from prototype function classes rather than the
solution and least squares classes. Simple examples are included with the
library.

This version includes concatenation operators, elementwise products for
matrices and GenericMatrices. See the sections on binary operators [3.6] and
unspecified types [3.16].

There is now no need to explicitly set the AT&T option in include.h.

I have reorganised the make files for AT&T, Gnu, Microsoft and Watcom. See the
files [6] section.


        2.4.2  Updating form previous versions
        =====  ======== ==== ======== ========

This is a minor upgrade on newmat07 to correct errors (one serious) and
improve compatibility with various compilers. You should upgrade.

*  .cxx files are now .cpp files. Some versions of won't accept .cpp. The
"make" files for Gnu and AT&T link the .cpp files to .cxx files before
compilation and delete the links after compilation.

*  An option [2.2] in include.h allows you to use compiler supported
exceptions, simulated exceptions or disable exceptions. Edit the file
include.h to select one of these three options. Don't simulate exceptions if
you have set your compiler's option to implement exceptions.

*  New QR decomposition [3.18] functions.

*  A non-linear least squares [3.26] class.

*  No need to explicitly set the AT&T option in include.h.

*  Concatenation and elementwise multiplication [3.6].

*  A new GenericMatrix [3.16] class.

*  Sum [3.8] function.

*  Some of the make [6] files reorganised. 


If you are upgrading from newmat06 note the following:

*  If you are using << to load a Real into a submatrix change this to =.


If you are upgrading from newmat03 or newmat04 note the following

*  .hxx files are now .h files

*  real changed to Real

*  BOOL changed to Boolean

*  CopyToMatrix changed to AsMatrix, etc

*  real(A) changed to A.AsScalar()


The current version is quite a bit longer that newmat04, so if you are almost
out of space with newmat04, don't throw newmat04 away until you have checked
your program will work under this version.

See the change history [1.7] for other changes.


        2.5  Example
        ===  =======

An example is given in  example.cpp.  This gives a simple linear regression
example using four different algorithms. The correct output is given in
example.txt. The program carries out a rough check that no memory is left
allocated on the heap when it terminates. See the section on testing [2.6] for
a comment on the reliability of this check and the use of the DO_FREE_CHECK
option.

I include a variety of make files. Use a command like

   gmake example -f gnu.mak               (Gnu G++)
   gmake example -f cc.mak                (AT&T, HPUX, Sun)
   nmake example -f ms_nt.mak             (Microsoft C++ 8.0)
   make -f ex_b.mak                       (Borland C++ 3.1)
   make -f ex_bc45.mak                    (Borland C++ 4.5)
   wmake example.exe -f watcom.mak        (Watcom C++ 10A)
   wmake example.exe -f watco_nt.mak      (Watcom C++ 10A)

The Borland files were derived from the project file and you will have to edit
these to suit your environment. The file ex_bc45.mak is for making a windows
NT executable program. The Microsoft file is for the version of C++ that came
with the Windows NT 3.1 development kit. The second Watcom file is for making
a Windows NT executable.

 ------------------------------------------------------------------------------
This example uses io manipulators. It will not work with a compiler that does
not support the standard io manipulators.
 ------------------------------------------------------------------------------