nm10.htm

matrix library for linux and windos

in C</I> interface, output operations, various scalar functions. Improved
return from functions. Reorganised setting options in &quot;include.hxx&quot;.
</P>
<P><B>Newmat02 - July 1991:</B> </P>
<P CLASS="small">Version with matrix row/column operations and numerous
additional functions. </P>
<P><B>Matrix - October 1990:</B> </P>
<P CLASS="small">Early version of package. </P>
<H2><A NAME="sources"></A>1.8 References</H2>
<P CLASS="small"><A HREF="#starting">next</A> - <A HREF="#starting">skip</A> -
<A HREF="#intro">up</A> - <A HREF="#top">start</A></P>
<UL>
<LI>The matrix LU decomposition is from Golub, G.H. &amp; Van Loan, C.F.
(1996), <I>Matrix Computations</I>, published by Johns Hopkins University
Press. </LI>
<LI>Part of the matrix inverse/solve routine is adapted from Press, Flannery,
Teukolsky, Vetterling (1988), <I>Numerical Recipes in C</I>, published by the
Cambridge University Press. </LI>
<LI>Many of the advanced matrix routines are adapted from routines in Wilkinson
and Reinsch (1971), <I>Handbook for Automatic Computation, Vol II, Linear
Algebra</I> published by Springer Verlag. </LI>
<LI>The fast Fourier transform is adapted from Carl de Boor (1980), <I>Siam J
Sci Stat Comput</I>, pp173-8 and the fast trigonometric transforms from Charles
Van Loan (1992) in <I>Computational frameworks for the fast Fourier
transform</I> published by SIAM. </LI>
<LI>The sort function is derived from Sedgewick, Robert (1992), <I>Algorithms
in C++</I> published by Addison Wesley. </LI>
</UL>
<P>For references about <I>Newmat</I> see </P>
<UL>
<LI>Davies, R.B. (1994) Writing a matrix package in C++. In OON-SKI'94: The
second annual object-oriented numerics conference, pp 207-213. Rogue Wave
Software, Corvallis. </LI>
<LI>Eddelbuttel, Dirk (1996) Object-oriented econometrics: matrix programming
in C++ using GCC and Newmat. Journal of Applied Econometrics, Vol 11, No 2, pp
199-209. </LI>
</UL>
<H2><A NAME="starting"></A>2. Getting started</H2>
<P CLASS="small"><A HREF="#overview">next</A> - <A HREF="#refer">skip</A> -
<A HREF="#top">up</A> - <A HREF="#top">start</A></P>
<TABLE WIDTH="100%">
<TR>
<TD VALIGN="TOP" ALIGN="LEFT" WIDTH="50%"> <A
HREF="#overview">2.1 Overview</A><BR>
<A HREF="#make">2.2 Make files</A><BR>
<A HREF="#custom">2.3 Customising</A><BR>
<A HREF="#compiler">2.4 Compilers</A><BR>
<a HREF="#update">2.5 Updating from previous versions</a><br>
<a HREF="#except_1">2.6 Catching exceptions</a></TD>
<TD VALIGN="TOP" ALIGN="LEFT" WIDTH="50%"> <A
HREF="#example">2.7 Example</A><BR>
<A HREF="#testing">2.8 Testing</A><BR>
<A HREF="#bugs">2.9 Bugs</A><BR>
<A HREF="#files">2.10 Files in newmat10</A><BR>
<A HREF="#problem">2.11 Problem report form</A></TD>
</TR>
</TABLE>
<H2><A NAME="overview"></A>2.1 Overview</H2>
<P CLASS="small"><A HREF="#make">next</A> - <A HREF="#make">skip</A> -
<A HREF="#starting">up</A> - <A HREF="#top">start</A></P>
<P>I use .h as the suffix of definition files and .cpp as the suffix of C++
source files. </P>
<P>You will need to compile all the *.cpp files listed as program files in the
<A HREF="#files">files section</A> to get the complete package. Ideally you
should store the resulting object files as a library. The tmt*.cpp files are
used for <A HREF="#testing">testing</A>, example.cpp is an <A
HREF="#example">example</A> and sl_ex.cpp, nl_ex.cpp and garch.cpp are examples
of the <A HREF="#nonlin">non-linear</A> solve and optimisation routines. A
demonstration and test of the exception mechanism is in test_exc.cpp. </P>
<P>I include a number of <I>make</I> files for compiling the example and the
test package. See the section on <A HREF="#make">make files</A> for details.
But with the PC compilers, its pretty quick just to load all the files in the
interactive environments by pointing and clicking. </P>
<P>Use the large or win32 console model when you are using a PC. Do not
<I>outline</I> inline functions. You may need to increase the stack size. </P>
<P>Your source files that access the newmat will need to #include one or more
of the following files. </P>
<TABLE WIDTH="100%" CELLPADDING="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<TR>
<TD VALIGN="TOP">include.h</TD>
<TD>to access just the compiler options</TD>
</TR>
<TR>
<TD VALIGN="TOP">newmat.h</TD>
<TD>to access just the main matrix library (includes include.h)</TD>
</TR>
<TR>
<TD VALIGN="TOP">newmatap.h</TD>
<TD>to access the advanced matrix routines such as Cholesky decomposition, QR
triangularisation etc (includes newmat.h)</TD>
</TR>
<TR>
<TD VALIGN="TOP">newmatio.h</TD>
<TD>to access the <A HREF="#output">output</A> routines (includes newmat.h) You
can use this only with compilers that support the standard input/output
routines including manipulators</TD>
</TR>
<TR>
<TD VALIGN="TOP">newmatnl.h</TD>
<TD>to access the non-linear optimisation routines (includes newmat.h)</TD>
</TR>
</TABLE>
<P>See the section on <A HREF="#custom">customising</A> to see how to edit
include.h for your environment and the section on <A
HREF="#compiler">compilers</A> for any special problems with the compiler you
are using. </P>
<H2><A NAME="make"></A>2.2 Make files</H2>
<P CLASS="small"><A HREF="#custom">next</A> - <A HREF="#custom">skip</A> -
<A HREF="#starting">up</A> - <A HREF="#top">start</A></P>
<P>I have included <I>make</I> files for CC, Microsoft, Intel, Borland 5.5 and Gnu compilers 
for compiling the examples. You 
can generate make files for a number of other compilers with my
<a href="genmake.htm">genmake</a> utility. Make files provide
a way of compiling your programs  without using the IDE that comes with
PC compilers. See the <A HREF="#files">files section</A> for details. See the
<A HREF="#example">example</A> for how to use them. Leave out the target name
to compile and link all my examples and test files. For more information on how 
to use these files see the documentation for my
<a href="genmake.htm">genmake</a> utility.</P>
<H3>PC</H3>
<P>I include make files for Microsoft, Intel, Borland 5.5. For Borland you will need to edit it to show where 
you have stored your Borland compiler. For make files for other compilers use my
<a href="genmake.htm">genmake</a> utility.</P>
<H3>Unix</H3>
<P>The <I>make</I> file for the Unix CC 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 <I>make</I>
file and, if necessary, rename the .cpp files to something your compiler
recognises. </P>
<P>My <I>make</I> file for Gnu GCC on Unix systems is for use with
<TT>gmake</TT> rather than <TT>make</TT>. I assume your compiler recognises the
.cpp extension. Ordinary <TT>make</TT> works with it on the Sun but not the
Silicon Graphics or HP machines. On Linux use <TT>make</TT>. </P>
<P>My make file for the CC compilers works with the ordinary make. </P>
<P>To compile everything with the CC compiler use </P>
<PRE>   make -f nm_cc.mak
</PRE>

<P>or for the gnu compiler use </P>
<PRE>   gmake -f nm_gnu.mak
</PRE>

<P>There is a line in the make file for CC <TT>rm -f $*.cxx</TT>. Some systems
won't accept this line and you will need to delete it. In this case, if you
have a bad compile and you are using my scheme for linking .cxx files, you will
need to delete the .cxx file link generated by that compile before you can do
the next one.</P>
<P>There is also a <i>make</i> file for the Intel compiler for Linux. </P>
<H2><A NAME="custom"></A>2.3 Customising</H2>
<P CLASS="small"><A HREF="#compiler">next</A> - <A HREF="#compiler">skip</A> -
<A HREF="#starting">up</A> - <A HREF="#top">start</A></P>
<P>The file <I>include.h</I> sets a variety of options including several
compiler 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. </P>
<P>Borland, Turbo, Gnu, Microsoft and Watcom are recognised automatically. If
none of these are recognised a default set of options is used. These are fine
for AT&amp;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. </P>
<P>There is an option in include.h for selecting whether you use compiler
supported exceptions, simulated exceptions, or disable exceptions. I now set
<I> compiler supported exceptions</I> as the default. Use the option for
compiler supported exceptions <I>if and only if</I> 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. </P>
<P>If you are using an older compiler that does <I>not</I> recognises<B>
bool</B> as required by the standard then <I>de-activate</I> the statement
<TT>#define bool_LIB</TT>. This will turn <I>on</I> my Boolean class. </P>
<P>Activate the appropriate statement to make the element type float or double.
</P>
<P>I suggest you leave the options TEMPS_DESTROYED_QUICKLY,
TEMPS_DESTROYED_QUICKLY_R <I>de-activated</I>, unless you are using a very old
version of Gnu compiler (&lt;2.6). This stores the <I>trees</I> describing
matrix expressions on the stack rather than the heap. See the discussion on
<A HREF="#destr">destruction of temporaries</A> for more explanation.</P>
<P>The option <A HREF="#testing">DO_FREE_CHECK</A> is used for tracking memory
leaks and normally should not be activated. </P>
<P>Activate SETUP_C_SUBSCRIPTS if you want to use traditional C style
<A HREF="#elements">element access</A>. Note that this does <I>not</I> change
the starting point for indices when you are using round brackets for accessing
elements or selecting submatrices. It does enable you to use C style square
brackets.</P>
<P>Activate <TT>#define use_namespace</TT> if you want to use <A
HREF="#namesp">namespaces</A>. Do this only if you are sure your compiler
supports namespaces. If you do turn this option on, be prepared to turn it off
again if the compiler reports inaccessible variables or the linker reports
missing links. </P>
<P>Activate <TT>#define _STANDARD_</TT> to use the standard names for the
included files and to find the floating point precision data using the floating
point standard. This will work only with the most recent compilers. This is 
automatically turned on for the Gnu compiler version 3 and the Intel compiler 
for Linux. </P>
<P>If you haven't defined <TT>_STANDARD_</TT> and are using a compiler that
<I>include.h</I> does not recognise and you want to pick up the floating point
precision data from <I>float.h</I> then activate <TT>#define use_float_h</TT>.
Otherwise the floating point precision data will be accessed from
<I>values.h</I>. You may need to do this with computers from Digital, in
particular. </P>
<H2><A NAME="compiler"></A>2.4 Compilers</H2>
<P CLASS="small"><A HREF="#atandt">next</A> - <A HREF="#update">skip</A> -
<A HREF="#starting">up</A> - <A HREF="#top">start</A></P>
<TABLE WIDTH="100%">
<TR>
<TD VALIGN="TOP" ALIGN="LEFT" WIDTH="50%">
<A HREF="#atandt">2.4.1 AT&amp;T </A><BR>
<A HREF="#borland">2.4.2 Borland </A><BR>
<A HREF="#gcc">2.4.3 Gnu G++ </A><BR>
<A HREF="#hpux">2.4.4 HPUX </A> </TD>
<TD VALIGN="TOP" ALIGN="LEFT" WIDTH="50%">
<A HREF="#intel">2.4.5 Intel </A><BR>
<A HREF="#microso">2.4.6 Microsoft </A><BR>
<A HREF="#sun">2.4.7 Sun </A><BR>
<A HREF="#watcom">2.4.8 Watcom </A></TD>
</TR>
</TABLE>
<P>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 PC versions,  I use Pentium 3 
&amp; 4 computers running windows 2000 or XP or various varieties of Linux
(Red Hat or Fedora). The Unix versions are on a Sun Sparc
station. Thanks to Victoria University for access to the Sparc. </P>
<P>I have set up a block of code for each of the compilers in include.h. Turbo,
Borland, Gnu, Microsoft and Watcom are recognised automatically. There is a
default option that works for AT&amp;T, Sun C++ 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. </P>
<H2><A NAME="atandt"></A>2.4.1 AT&amp;T</H2>
<P CLASS="small"><A HREF="#borland">next</A> - <A HREF="#borland">skip</A> -
<A HREF="#compiler">up</A> - <A HREF="#top">start</A></P>
<P>The AT&amp;T compiler used to be available on a wide variety of Unix
workstations. I don't know if anyone still uses it. However the AT&amp;T options are 
the default if your compiler is not recognised.</P>
<P>AT&amp;T C++ 2.1; 3.0.1 on a Sun: Previous versions worked on these
compilers, which I no longer have access to. </P>
<P>In AT&amp;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. </P>
<H2><A NAME="borland"></A>2.4.2 Borland</H2>
<P CLASS="small"><A HREF="#gcc">next</A> - <A HREF="#gcc">skip</A> -
<A HREF="#compiler">up</A> - <A HREF="#top">start</A></P>
<H3>Newer compilers</H3>
<P><b>Borland Builder version 6:</b> This is <b>not</b> compatible with <i>
newmat10</i>. Use <i>newmat11</i> instead.</P>
<P><B>Borland Builder version 5:</B> This works fine in console mode and no
special editing of the source codes is required. I haven't tested it in GUI
mode. You can set the <i>newmat10</i> options to use namespace and the standard 
library. <b> You
should turn <I>off</I> the Borland option to use pre-compiled headers.</b> There 
are notes on compiling with the IDE on my <a href="#where">website</a>. 
Alternatively you can use the <i>nm_b55.mak</i> make file<i>.</i></P>
<P><B>Borland Builder version 4</B>: I have successfully used this on older 
versions of newmat using the
console wizard (menu item file/new - select new tab). Use compiler
exceptions. Suppose you are compiling my test program <I>tmt</I>. Rename my
<I>main()</I> function in <I>tmt.cpp</I> to <I>my_main()</I>. Rename
<I>tmt.cpp</I> to <I>tmt_main.cpp</I>. Borland will generate a new file
<I>tmt.cpp</I> containing their <I>main()</I> function. Put the line <TT>int
my_main();</TT> above this function and put <TT>return my_main();</TT> into the
body of <I>main()</I>.</P>
<P><B>Borland compiler version 5.5</B>: this is the free C++ compiler available
from Borland's web site. I suggest you use
the compiler supported exceptions and turn on <I>standard</I> in include.h. You
can use the make file <i>nm_b55.mak</i> after editing to correct the file locations for
your system.</P>
<H3>Older compilers</H3>
<P><B>Borland C++ 3.1,  5.02</B>: Use the simulated exceptions with these. Then 
version 5.02 works OK.  You will need to use 
the large or 32 bit flat model. If you are not debugging, turn off the options 
that collect debugging information. It compiles with version 3.1 but you can't 
run the tmt test program.</P>
<P>If you are using versions earlier than 5 remember to edit include.h to
activate my Boolean class. </P>
<P>When running my test program under ms-dos you may run out of memory. Either
compile the test routine to run under <I>easywin</I> or use simulated exceptions 
rather than the built in exceptions. </P>
<P>If you can, upgrade to windows 9X or window NT and use the 32 bit console
model. </P>
<P>If you are using the 16 bit large model, don't forget to keep all matrices
less than 64K bytes in length (90x90 for a rectangular matrix if you are using
<TT>double</TT> as your element type). Otherwise your program will crash
without warning or explanation. You will need to break the <A
HREF="#testing">tmt</A> set of test files into several parts to get the program 
to fit into your computer and run without stack overflow. </P>
<P>One version of Borland had DBL_MIN incorrectly defined. If you are using an
older version of Borland and are getting strange numerical errors in the test
programs reinstate the commented out statements in precision.h. </P>
<P>You can generate make files for versions 5 or 3.1 with my <a href="genmake.htm">
genmake</a> utility.</P>