home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / mesch12a.zip / README < prev    next >
Text File  |  1994-02-14  |  18KB  |  433 lines
  1.  
  2.  
  3.                      
  4.                  Meschach Library
  5.                    Version 1.2a
  6.  
  7.  
  8.                  David E. Stewart
  9.             (david.stewart@anu.edu.au)
  10.  
  11.                     and
  12.  
  13.                    Zbigniew Leyk
  14.             (zbigniew.leyk@anu.edu.au)
  15.  
  16.               School of Mathematical Sciences
  17.               Australian National University
  18.                  Canberra ACT 0200
  19.                  Australia
  20.  
  21.  
  22.               [last revised: 14/1/94]
  23.  
  24.  
  25.                   1. INTRODUCTION
  26.  
  27.    The Meschach Library is a numerical library of C routines for performing
  28. calculations on matrices and vectors. It is intended for solving systems of
  29. linear equations (dense and sparse), solve least squares problems,
  30. computing eigenvalues and eigenvectors, etc. We do not claim that it
  31. contains every useful algorithm in numerical linear algebra, but it does
  32. provide a basis on which more advanced algorithms can be built. The library
  33. is for people who know something about the C programming language,
  34. something of how to solve the numerical problem they are faced with but do
  35. not want to have the hassle of building all the necessary routines from the
  36. scratch. The library is not a loose collection of numerical routines but it
  37. comprises a coherent system. The current version is enhanced with many
  38. features comparing with previous versions. Since the memory requirements
  39. are nontrivial for large problems we have paid more attention to
  40. allocation/deallocation of memory.
  41.  
  42.    The source code is available to be perused, used and passed on without
  43. cost, while ensuring that the quality of the software is not compromised.
  44. The software is copyrighted; however, the copyright agreement follows in
  45. the footsteps of the Free Software Foundation in preventing abuse that
  46. occurs with totally public domain software.
  47.  
  48.    Detailed instructions for installing Meschach are contained below.
  49.  
  50.    Pronunciation: if in doubt, say "me-shark".  This is close enough.
  51. Don't ask us "Why call it that?"  Have a look at the quote at the front of
  52. the manual.
  53.  
  54.  
  55.                   2. AVAILABILITY
  56.  
  57.     The authors make this code openly available to others, in the hope that
  58. it will prove to be a useful tool.  We ask only that:
  59.  
  60. * If you publish results obtained using Meschach, please consider
  61.   acknowledging the source of the code.
  62.  
  63. * If you discover any errors in the code, please promptly communicate them
  64.   to the authors.
  65.  
  66.     We also suggest that you send email to the authors identifying yourself
  67. as a user of Meschach; this will enable the authors to notify you of any
  68. corrections/improvements in Meschach.
  69.  
  70.  
  71.  
  72.                  3. HOW TO GET IT
  73.  
  74.    There are several different forms in which you might receive Meschach.
  75. To provide a shorthand for describing collections of files, the Unix
  76. convention of putting alternative letters in [...] will be used.  (So,
  77. fred[123] means the collection fred1, fred2 and fred3.)  Meschach is
  78. available over Internet/AARnet via netlib, or at the anonymous ftp site
  79. thrain.anu.edu.au in the directory pub/meschach.  There are five .shar
  80. files: meschach[01234].shar (which contain the library itself),
  81. meschach0.shar (which contains basic documentation and machine dependent
  82. files for a number of machines).  Of the meschach[1234].shar files, only
  83. meschach[12].shar are needed for the basic Meschach library; the third
  84. .shar file contains the sparse matrix routines, and the the fourth contains
  85. the routines for complex numbers, vectors and matrices.  There is also a
  86. README file that you should get from meschach0.shar.
  87.  
  88.    If you need the old iterative routines, the file oldmeschach.shar
  89. contains the files conjgrad.c, arnoldi.c and lanczos.c.
  90.  
  91.    To get the library from netlib,
  92.  
  93. mail netlib@research.att.com
  94. send all from c/meschach
  95.  
  96.    There are a number of other netlib sites which mirror the main netlib
  97. sites.  These include netlib@ornl.gov (Oak Ridge, TN, USA), netlib@nac.no
  98. (Oslo, Norway), ftp.cs.uow.edu.au (Wollongong, Australia; ftp only),
  99. netlib@nchc.edu.tw (Taiwan), elib.zib-berlin.de (Berlin, Germany; ftp
  100. only).  (For anonymous ftp sites the directory containing the Meschach
  101. .shar files is pub/netlib/c/meschach or similar, possibly depending on the
  102. site.)
  103.  
  104.    Meschach is available in other forms on thrain.anu.edu.au by ftp in the
  105. directory pub/meschach.  It is available as a .tar file (mesch12a.tar for
  106. version 1.2a), or as a collection of .shar files, or as a .zip file.  The
  107. .tar and .zip versions each contain the entire contents of the Meschach
  108. library.
  109.  
  110.  
  111.  
  112.                   4. INSTALLATION
  113.  
  114.                 a) On Unix machines
  115.  
  116.    To extract the files from the .shar files, put them all into a suitable
  117. directory and use
  118.  
  119.   sh <file>.shar
  120.  
  121. to expand the files.  (Use one sh command per file; sh *.shar will not work
  122. in general.)
  123.  
  124.    For the .tar file, use
  125.  
  126.   tar xvf mesch12a.tar
  127.  
  128. and for the .zip file use
  129.  
  130.   unzip mesch12a.zip
  131.  
  132.    On a Unix system you can use the configure script to set up the
  133. machine-dependent files.  The script takes a number of options which are
  134. used for installing different subsets of the full Meschach.  For the basic
  135. system, which requires only meschach[012].shar, use
  136.  
  137.   configure
  138.   make basic
  139.   make clean
  140.  
  141.    For including sparse operations, which requires meschach[0123].shar, use
  142.  
  143.   configure --with-sparse
  144.   make sparse
  145.   make clean
  146.  
  147.   For including complex operations, which requires meschach[0124].shar, use
  148.  
  149.   configure --with-complex
  150.   make complex
  151.   make clean
  152.  
  153.    For including everything, which requires meschach[01234].shar, use
  154.  
  155.   configure --with-all
  156.   make all
  157.   make clean
  158.  
  159.   To compile the complete library in single precision (with Real equivalent
  160. to float), add the --with-float option to configure, use
  161.  
  162.   configure --with-all --with-float
  163.   make all
  164.   make clean
  165.  
  166.  
  167.    Some Unix-like systems may have some problems with this due to bugs or
  168. incompatibilities in various parts of the system.  To check this use make
  169. torture and run torture.  In this case use the machine-dependent files from
  170. the machines directory.  (This is the case for RS/6000 machines, the -O
  171. switch results in failure of a routine in schur.c.  Compiling without the
  172. -O switch results in correct results.)
  173.  
  174.    If you have problems using configure, or you use a non-Unix system,
  175. check the MACHINES directory (generated by meschach0.shar) for your
  176. machine, operating system and/or compiler.  Save the machine dependent
  177. files makefile, machine.c and machine.h.  Copy those files from the
  178. directory for your machine to the directory where the source code is.
  179.  
  180.    To link into a program prog.c, compile it using
  181.  
  182.   cc -o prog_name prog.c ....(source files).... meschach.a -lm
  183.  
  184.  
  185.    This code has been mostly developed on the University of Queensland,
  186. Australia's Pyramid 9810 running BSD4.3.  Initial development was on a
  187. Zilog Zeus Z8000 machine running Zeus, a Unix workalike operating system.
  188. Versions have also been successfully used on various Unix machines
  189. including Sun 3's, IBM RT's, SPARC's and an IBM RS/6000 running AIX.  It
  190. has also been compiled on an IBM AT clone using Quick C.  It has been
  191. designed to compile under either Kernighan and Richie, (Edition 1) C and
  192. under ANSI C.  (And, indeed, it has been compiled in both ANSI C and
  193. non-ANSI C environments.)
  194.  
  195.  
  196.               b) On non-Unix machines
  197.  
  198.    First look in the machines directory for your system type.  If it is
  199. there, then copy the machine dependent files machine.h, makefile (and
  200. possibly machine.c) to the Meschach directory.
  201.  
  202.    If your machine type is not there, then you will need to either compile
  203. ``by hand'', or construct your own makefile and possibly machine.h as well.
  204. The machine-dependent files for various systems should be used as a
  205. starting point, and the ``vanilla'' version of machine.h should be used.
  206. Information on the machine-dependent files follows in the next three
  207. subsections.
  208.  
  209.    On an IBM PC clone, the source code would be on a floppy disk. Use
  210.  
  211.   xcopy a:* meschach
  212.  
  213. to copy it to the meschach directory.  Then ``cd meschach'', and then
  214. compile the source code.  Different compilers on MSDOS machines will
  215. require different installation procedures.  Check the directory meschach
  216. for the appropriate ``makefile'' for your compiler.  If your compiler is
  217. not listed, then you should try compiling it ``by hand'', modifying the
  218. machine-dependent files as necessary.
  219.  
  220.    Worst come to worst, for a given C compiler, execute
  221.         <C compiler name> *.c
  222. on MS-DOS machines. For example,
  223.         tcc *.c
  224. for Turbo C, and
  225.         msc *.c
  226. for Microsoft C, or if you are using Quick C,
  227.         qcl *.c
  228. and of course
  229.         cc *.c
  230. for the standard Unix compiler.
  231.  
  232.    Once the object files have been generated, you will need to combine them
  233. into a library. Consult your local compiler's manual for details of how to
  234. do this.
  235.  
  236.    When compiling programs/routines that use Meschach, you will need to
  237. have access the the header files in the INCLUDE directory. The INCLUDE
  238. directory's contents can be copied to the directory where the
  239. programs/routines are compiled.
  240.  
  241.    The files in the DOC directory form a very brief form of documentation
  242. on the the library routines in Meschach. See the printed documentation for
  243. more comprehensive documentation of the Meschach routines.  This can be
  244. obtained from the authors via email.
  245.  
  246.    The files and directories created by the machines.shar shell archive
  247. contain the files machine.c machine.h and makefile for a particular
  248. machine/operating system/compiler where they need to be different.  Copy
  249. the files in the appropriate directory for your machine/operating
  250. system/compiler to the directory with the Meschach source before compiling.
  251.  
  252.  
  253.  
  254.                    c)  makefile
  255.  
  256.  
  257.    This is setup by using the configure script on a Unix system, based on
  258. the makefile.in file.  However, if you want to modify how the library is
  259. compiled, you are free to change the makefile.
  260.  
  261.    The most likely change that you would want to make to this file is to
  262. change the line
  263.  
  264.   CFLAGS = -O
  265.  
  266. to suit your particular compiler.
  267.  
  268.   The code is intended to be compilable by both ANSI and non-ANSI
  269. compilers.
  270.  
  271.    To achieve this portability without sacrificing the ANSI function
  272. prototypes (which are very useful for avoiding problems with passing
  273. parameters) there is a token ANSI_C which must be #define'd in order to
  274. take full advantage of ANSI C.  To do this you should do all compilations
  275. with
  276.  
  277.   #define ANSI_C 1
  278.  
  279.    This can also be done at the compilation stage with a -DANSI_C flag.
  280. Again, you will have to use the -DANSI_C flag or its equivalent whenever
  281. you compile, or insert the line
  282.  
  283.   #define ANSI_C 1
  284.  
  285. in machine.h, to make full use of ANSI C with this matrix library.
  286.  
  287.  
  288.                    d)  machine.h
  289.  
  290.    Like makefile this is normally set up by the configure script on Unix
  291. machines.  However, for non-Unix systems, or if you need to set some things
  292. ``by hand'', change machine.h.
  293.  
  294.    There are a few quantities in here that should be modified to suit your
  295. particular compiler.  Firstly, the macros MEM_COPY() and MEM_ZERO() need to
  296. be correctly defined here.  The original library was compiled on BSD
  297. systems, and so it originally relied on bcopy() and bzero().
  298.  
  299.    In machine.h you will find the definitions for using the standard ANSI C
  300. library routines:
  301.  
  302.   /*--------------------ANSI C--------------------*/
  303.   #include        <stddef.h>
  304.   #include        <string.h>
  305.   #define    MEM_COPY(from,to,size)  memmove((to),(from),(size))
  306.   #define    MEM_ZERO(where,size)    memset((where),'\0',(size))
  307.  
  308.    Delete or comment out the alternative definitions and it should compile
  309. correctly.  The source files containing memmove() and/or memset() are
  310. available by anonymous ftp from some ftp sites (try archie to discover 
  311. them). The files are usually called memmove.c or memset.c.
  312. Some ftp sites which currently (Jan '94) have a version of these files are
  313. munnari.oz.au (in Australia), ftp.uu.net, gatekeeper.dec.com (USA), and
  314. unix.hensa.ac.uk (in the UK).  The directory in which you will find
  315. memmove.c and memset.c typically looks like .../bsd-sources/lib/libc/...
  316.  
  317.    There are two further machine-dependent quantities that should be set.
  318. These are machine epsilon or the unit roundoff for double precision
  319. arithmetic, and the maximum value produced by the rand() routine, which is
  320. used in rand_vec() and rand_mat().
  321.  
  322.  
  323.    The current definitions of these are
  324.  
  325.   #define    MACHEPS    2.2e-16
  326.   #define    MAX_RAND 2.147483648e9
  327.  
  328.    The value of MACHEPS should be correct for all IEEE standard double
  329. precision arithmetic.
  330.  
  331.    However, ANSI C's <float.h> contains #define'd quantities DBL_EPSILON
  332. and RAND_MAX, so if you have an ANSI C compiler and headers, replace the
  333. above two lines of machine.h with
  334.  
  335.   #include <float.h>
  336.   /* for Real == float */
  337.   #define MACHEPS DBL_EPSILON
  338.   #define MAX_RAND RAND_MAX
  339.  
  340.    The default value given for MAX_RAND is 2^31 , as the Pyramid 9810 and
  341. the SPARC 2's both have 32 bit words.  There is a program macheps.c which
  342. is included in your source files which computes and prints out the value of
  343. MACHEPS for your machine.
  344.  
  345.    Some other macros control some aspects of Meschach.  One of these is
  346. SEGMENTED which should be #define'd if you are working with a machine or
  347. compiler that does not allow large arrays to be allocated.  For example,
  348. the most common memory models for MS-DOS compilers do not allow more than
  349. 64Kbyte to be allocated in one block.  This limits square matrices to be no
  350. more than 9090 .  Inserting #define SEGMENTED 1 into machine.h will mean
  351. that matrices are allocated a row at a time.
  352.  
  353.  
  354.  
  355.                   4. SAMPLE TESTS
  356.  
  357.     There are several programs for checking Meschach called torture
  358. (source: torture.c) for the dense routines, sptort (source: sptort.c) for
  359. the sparse routines, ztorture (source ztorture.c) for a complex version of
  360. torture, memtort (source memtort.c) for memory allocation/deallocation,
  361. itertort (source itertort.c) for iterative methods, mfuntort (source
  362. mfuntort.c) for computing powers of dense matrices, iotort (source
  363. iotort.c) for I/O routines.  These can be compiled using make by "make
  364. torture", "make sptort", etc.  The programs are part of meschach0.shar.
  365.  
  366.  
  367.                  5. OTHER PROBLEMS
  368.  
  369.    Meschach is not a commercial package, so we do not guarantee that
  370. everything will be perfect or will install smoothly.  Inevitably there will
  371. be unforseen problems. If you come across any bugs or inconsistencies, please
  372. let us know.  If you need to modify the results of the configure script, or
  373. need to construct your own machine.h and makefile's, please send them to
  374. us.  A number of people sent us the machine dependent files for Meschach 1.1,
  375. but with the use of configure, and the new information needed for version
  376. 1.2, these machine dependent files don't have quite the right information.
  377. Hopefully, though, they are redundant.  Non-Unix platforms at present
  378. require ``manual'' installation.  Because of the variety of platforms
  379. (MS-DOS, Macintosh, VAX/VMS, Prime, Amiga, Atari, ....) this is left up to
  380. the users of these platforms.  We hope that you can use the distibutable
  381. machine-dependent files as a starting point for this task.
  382.  
  383.    If you have programs or routines written using Meschach v.1.1x, you
  384. should put the statement
  385.  
  386.    #include "oldnames.h"
  387.  
  388. at the beginning of your files.  This is because a large number of the
  389. names of the routines have been changed (e.g. "get_vec()" has become
  390. "v_get()").  This will enable you to use the old names, although all of the
  391. error messages etc., will use the new names.  Also note that the new
  392. iterative routines have a very different calling sequence.  If you need the
  393. old iterative routines, they are in oldmeschach.shar.
  394.  
  395.    If you wish to let us know what you have done, etc., our email
  396. addresses are
  397.  
  398.              david.stewart@anu.edu.au
  399.              zbigniew.leyk@anu.edu.au
  400.  
  401.     Good luck!
  402.  
  403.  
  404.                   ACKNOWLEDGMENTS
  405.  
  406.  
  407.     Many people have helped in various ways with ideas and suggestions.
  408. Needless to say, the bugs are all ours!  But these people should be thanked
  409. for their encouragement etc.  These include a number of people at
  410. University of Queensland: Graeme Chandler, David De Wit, Martin Sharry,
  411. Michael Forbes, Phil Kilby, John Holt, Phil Pollett and Tony Watts.  At the
  412. Australian National University: Mike Osborne, Steve Roberts, Margaret Kahn
  413. and Teresa Leyk.  Karen George of the University of Canberra has been a
  414. source of both ideas and encouragement.  Email has become significant part
  415. of work, and many people have pointed out bugs, inconsistencies and
  416. improvements to Meschach by email.  These people include Ajay Shah of the
  417. University of Southern California, Dov Grobgeld of the Weizmann Institute,
  418. John Edstrom of the University of Calgary, Eric Grosse, one of the netlib
  419. organisers, Ole Saether of Oslo, Norway, Alfred Thiele and Pierre
  420. Asselin of Carnegie-Mellon Univeristy, Daniel Polani of the University of
  421. Mainz, Marian Slodicka of Slovakia, Kaifu Wu of Pomona, Hidetoshi
  422. Shimodaira of the University of Tokyo, Eng Siong of Edinburgh, Hirokawa Rui
  423. of the University of Tokyo, Marko Slyz of the University of Michigan, and
  424. Brook Milligan of the University of Texas.  This list is only partial, and
  425. there are many others who have corresponded with us on details about
  426. Meschach and the like.  Finally our thanks go to all those that have had to
  427. struggle with compilers and other things to get Meschach to work.
  428.  
  429.                      
  430.  
  431.  
  432.  
  433.