ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / maths / rlab / docs / RLAB-R~1 < prev next >

Wrap

Text File | 1996-11-02 | 24.0 KB | 615 lines

<HTML> <HEAD> <TITLE> Rlab2 Reference Manual: Introduction</TITLE> </HEAD> <BODY> <IMG SRC="prev.gif" ALT="Previous"> <A HREF="rlab-ref-2.html"><IMG SRC="next.gif" ALT="Next"></A> <A HREF="rlab-ref.html#toc1"><IMG SRC="toc.gif" ALT="Contents"></A> <HR> <H2><A NAME="s1">1. Introduction</A></H2> Rlab stands for ``our'' lab. It is available to almost everyone who needs a computational tool for scientific and engineering applications, because it is freely available, and it runs on many platforms. For many years scientists and engineers have developed and implemented programs in low-level programming languages such as Algol, Fortran, Pascal, and C. As computers get faster, and more people program them, high level languages have become more popular. Most high level languages are tailored towards a particular task, or class of tasks, this is not a shortcoming, but a direct consequence of the high level nature of a language. If a language is supposed to be easy, convenient, for a particular set of tasks, some assumptions about those tasks must be made. There is a cost associated with the assumptions made with any high level language. In the realm of scientific languages the price is usually slower program execution time. However, as tasks become more complex, and computers get faster, the penalty for slower execution time is less. Often the slower execution time is more than compensated for by the significantly reduced development time. Rlab, a high level language for engineers and scientists makes several assumptions: <UL> <LI> The user is interested in computational exercises. Rlab offers little if any convenience for those who need help with symbolic programming. </LI> <LI> The operations, and conventions of linear algebra are useful in accomplishing most tasks. Rlab offers simple access to the most popular linear algebra libraries, BLAS, and LAPACK. Furthermore, Rlab's basic data structures are matrix oriented, with the vector dot-product an integral part of the built-in operations. Due to the array oriented operations, and the high-level interface to FFTPACK, and a discrete IIR filtering function, Rlab servers well as an environment for signal analysis and exploration. </LI> <LI> The language should be simple, yet predictable, with its origins in popular scientific languages that most engineers/scientists are likely to already be familiar with. Thus, Rlab takes after the C and Fortran programming languages, and to some extent Matlab, a popular (commercial) high level matrix language. </LI> </UL> I hope you find it useful ... <H2><A NAME="ss1.1">1.1 Background</A></H2> I started working with high level languages when I realized I was spending far too much time writing Fortran and C language programs as a part of engineering analyses, test data reduction, and continuing education. I searched for a better engineering programming tool; except for Matlab, and some Matlab-like programs (all commercial), I came up empty-handed (this was in 1989). I did not feel Matlab's language design was powerful enough, but I would have used it had it been lower in cost and available on more platforms. I diverted my ``off-hour'' studies to interpreter construction, and started prototyping Rlab. Within a year, I released version 0.10 to the Internet for comment. Now, almost five years later, Rlab has undergone significant changes and improvements primarily due to excellent assistance from users around the world. Rlab does not try to be a Matlab clone. Instead, it borrows what I believe are the best features of the Matlab language and provides improved language syntax and semantics. The syntax has been improved to allow users more expression and reduce ambiguities. The variable scoping rules have been improved to facilitate creation of larger programs and program libraries. A heterogeneous associative array has been added to allow users to create and operate on arbitrary data structures. This manual is intended to provide everything someone would need to know to use Rlab. Sometimes this document may be terse, and sometimes verbose. Instead of providing formal definitions of the syntax and semantics of the language the program will be described via discussion and examples. While this is likely to take more space than a precise description of the language, it will be more useful to most users. With that in mind, some might ask ``why not call it the Rlab User's Manual''? Well, there probably should be two manuals, but I am only one person and do not have the time or the patience for both. <H2><A NAME="ss1.2">1.2 Installation</A></H2> <H3>Overview</H3> Rlab has been ported to many platforms, so it should not be too difficult to get it to compile on your particular computer. At one time or another Rlab has been ported to the following platforms: <OL> <LI> SCO Unix</LI> <LI> UnixWare</LI> <LI> Linux, both a.out and ELF</LI> <LI> SunOS-4.1.x</LI> <LI> Solaris 2.x</LI> <LI> SGI Irix</LI> <LI> HP-UX 9.0x</LI> <LI> AIX 3.2.x</LI> <LI> DEC Ultrix 4.x</LI> <LI> Digital Unix (OSF v2.x on an Alpha)</LI> <LI> Acorn RISC-OS</LI> <LI> DOS (DJGPP)</LI> <LI> OS/2 </LI> <LI> Mac-OS</LI> </OL> Although Rlab(2) is not currently ported to all the mentioned platforms, the code is still fairly portable. The basic code is ANSI-C, so any platform with an ANSI-C compiler and library should be able to run the most basic part of Rlab; the interpreter, numerical functions, and data visualization. Although the author prefers Plplot, Gnuplot is probably the more portable of the two graphics packages. <H3>Quick Install</H3> This section will present the most basic of Rlab installations, as briefly as possible. The assumptions are that everything will be installed in <CODE>/usr/local</CODE>, you will use Gnuplot for graphics, and your platform has an ANSI-C compiler. <OL> <LI> Download the necessary files: <OL> <LI> The Rlab source code: <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlab2.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlab2.tgz</A> </LI> <LI> The BLAS source code: <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rblas.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rblas.tgz</A> </LI> <LI> The LAPACK source code: <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlap.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlap.tgz</A> </LI> <LI> The FFTPACK source code: <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rfft.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rfft.tgz</A> </LI> <LI> The RANLIB source code: <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rnlib.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rnlib.tgz</A> </LI> </OL> You can also get these files (with similar names) at: <A HREF="ftp://mirriwinni.cse.rmit.edu.au/pub/rlab">ftp://mirriwinni.cse.rmit.edu.au/pub/rlab</A> You might also choose to install a pre-compiled (or binary) version of Rlab. This is usually the fastest, and simplest method. You can check the Rlab web-page at: <A HREF="httpp://www.eskimo.com/~ians/rlab.html">httpp://ftp.eskimo.com/~ians/rlab.html</A> Archive sites that contain pre-compiled versions are often listed there. </LI> <LI> Compile and install each library. This is pretty simple. The library sources are all C-language, and there are no special porting considerations. There is a configure script which will generate a <CODE>Makefile</CODE> for each package. The basic steps for each library are (using rblas.tgz as an example): <OL> <LI> <CODE>gunzip rblas.tgz</CODE></LI> <LI> <CODE>tar -xvf rblas.tar</CODE></LI> <LI> <CODE>cd rblas*</CODE></LI> <LI> <CODE>./configure</CODE></LI> <LI> <CODE>make</CODE></LI> <LI> <CODE>make install</CODE></LI> </OL> </LI> <LI> Build Rlab, do: <OL> <LI> <CODE>gunzip rlab.tgz</CODE></LI> <LI> <CODE>tar -xvf rlab.tar</CODE></LI> <LI> <CODE>./configure --with-gnuplot</CODE></LI> <LI> <CODE>make gc</CODE></LI> <LI> <CODE>make rlab</CODE></LI> <LI> <CODE>make check</CODE></LI> <LI> <CODE>make install</CODE></LI> </OL> </LI> </OL> At this point you should have Rlab installed and ready to run. Of course there are many opportunities for trouble. If you do run into trouble you should try reading the Detailed Installation section, or check the <CODE>PROBLEMS</CODE> file contained in the Rlab source distribution. <H3>Detailed Installation</H3> This section provides significantly more detail and discussion than the Quick Installation Section. First a note about installation and packaging philosophy. Rlab is not bundled together with the sources for every package that it uses for several reasons. The first is package size. The total package size would be well over five mega-bytes. Secondly, most of the library (BLAS, LAPACK, etc.) code does not change very frequently, rebuilding it every time you re-build Rlab would be a waste. Finally, many of the supporting packages like the BLAS, and FFTPACK might already be on your computer in some sort of "optimized" form, maybe supplied by the vendor. A fully functional Rlab installation can consist of many parts. So, it is good to be patient, and take the build one step at a time. Rlab is developed on a Unix platform (Linux), and these installation steps are geared towards building it on Unix-like systems. The first step to building RLab is to decide what configuration you would like to build. Most of the options are: <DL> <DT>Graphics<DD>Rlab can use Plplot or Gnuplot to handle the data visualization chores. Plplot is a library that Rlab can link to. Gnuplot is a stand-alone program that Rlab can use via its I/O capabilities to interactively plot/visualize data. <DT>Dynamic-Linking<DD>If your computer's operating system supports dynamic linking (shared objects) well, then you can use this feature within Rlab to load functions at runtime. <DT>SuperLU<DD>The SuperLU package is a library for direct factorization of large sparse matrices using a supernodal technique. not implemented yet <DT>UMFPACK<DD>The UMFPACK library contains routines for performing direct factorization of large sparse matrices. The license on this package is pretty restrictive (research and educational only). <DT>Metis<DD>Metis is a package for partitioning and ordering graphs. This library can be used by Rlab to compute fill reducing permutation vectors for sparse matrices. <DT>Garbage-Collection (GC)<DD>Rlab-2 is designed to use Boehm's generational garbage collector. The code for the collector comes with Rlab, The configure/build process will try to use GC by default. If you absolutely can't get GC to build, then you can disable it. <DT>Using a Fortran Compiler<DD>A Fortran-77 compiler can be used for most of the supporting numerical analyses libraries (BLAS, LAPACK, FFTPACK, and RANLIB). Sometime using a Fortran compiler will produce libraries with better performance (speed). Sometimes the difference is large, and sometimes not. It really depends upon the computer architecture and the compilers. One of the drawbacks to using a Fortran compiler is the almost total lack of standardization of consistent conventions from vendor to vendor. This makes the task of auto-configuring for Fortran compilation too difficult. If you want to compile the libraries with a Fortran compiler there are examples and guidelines for some of the more popular platforms. If you have never attempted this before, you should consider building Rlab entirely with a C-compiler first, so that you have a working version while you get the Fortran libraries built. </DL> Enabling any of the above options requires that you have built and installed some sort of program or library on your system. There are other libraries and programs that you will need to build Rlab: <DL> <DT>BLAS<DD>The Basic Linear Algebra Subroutines provide services for almost all of the other numerical subroutines. <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rblas.tar.gz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rblas.tar.gz</A> <DT>LAPACK<DD>The Linear Algebra PACKage provides the majority of linear algebra functionality for Rlab. <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlap.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlap.tgz</A> <DT>FFTPACK<DD>Fast Fourier Transform PACKage provides the discrete Fourier transform and inverse transform capability. <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rfft.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rfft.tgz</A> <DT>RANLIB<DD>A library of Fortran routines for random number generation. This library provides all of the functionality for producing random numbers from a selection of distributions. <A HREF="ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rnlib.tgz">ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rnlib.tgz</A> </DL> All of the above libraries should be available from the same place you picked up the Rlab sources. Many of them are also available from Netlib ( <A HREF="ftp://netlib.att.com/">ftp://netlib.att.com/</A>) Rlab uses GNU autoconfigure to automatically detect operating system features and installed programs. Under the luckiest of circumstances you can configure Rlab by simply typing <CODE>./configure</CODE>. Under more normal circumstances you may need to give configure some help finding libraries, etc. Some of the most commonly used configure options are: <DL> <DT>--prefix=dir<DD><CODE>dir</CODE> is the root directory where Rlab, and its support files will be installed. Without user intervention <CODE>dir</CODE> defaults to <CODE>/usr/local/lib</CODE>. <DT>--with-LIBS=dir<DD><CODE>dir</CODE> is a directory where configure should look for libraries. This could be <CODE>/usr/local/lib</CODE> on many systems. <DT>--with-NALIBS=dir<DD><CODE>dir</CODE> is a directory where configure should look for numerical analysis libraries. Specifically, configure looks for <CODE>libClapack</CODE>, <CODE>libCblas</CODE>, <CODE>libCfftpack</CODE>, and <CODE>libCfftpack</CODE>. These libraries can be static, or shared libraries. Configure tries to compile, and link a simple program with each library. If configure can do this successfully, then it adds the library name to the list of "found" libraries. <DT>--with-FLIBS=dir<DD><CODE>dir</CODE> is the directory where the f2c libraries can be found. The f2c libraries are necessary to resolve undefined externals in the translated Fortran sources for the libraries. </DL> <H2><A NAME="ss1.3">1.3 Getting Started</A></H2> This section provides a quick-start so the reader can run rlab and try the examples, and ideas presented herein. It is assumed that the user will run rlab from the command-line on some sort of Unix-like system. Although Rlab runs on DOS, OS/2, Apple, and other operating systems, only Unix systems will be covered in this manual. To run rlab type: <BLOCKQUOTE><CODE> <PRE> $ rlab Welcome to RLaB. New users type `help INTRO' RLaB version 2.0b1b Copyright (C) 1992-95 Ian Searle RLaB comes with ABSOLUTELY NO WARRANTY; for details type `help WARRANTY' This is free software, and you are welcome to redistribute it under certain conditions; type `help CONDITIONS' for details > </PRE> </CODE></BLOCKQUOTE> The <CODE>></CODE> displayed after the startup message is the rlab prompt. At this point rlab is waiting for input. The expected input is a program. The simplest and most often used introductory program is: <BLOCKQUOTE><CODE> <PRE> > "Hello World" Hello World </PRE> </CODE></BLOCKQUOTE> Rlab echoes its input, unless it is directed not to. To silence Rlab end each statement with a <CODE>;</CODE> Rlab provides an environment. The environment consists of a global workspace occupied by variables. Local workspaces are created on demand by functions. When executing commands/programs interactively from the command line the programs execute within the global workspace. Those familiar with Fortran or the C-language can think of the global workspace as the main program. Any program that can be executed interactively, can also be executed in batch mode by typing the program in a file, and executing Rlab with the filename as an argument. <BLOCKQUOTE><CODE> <PRE> % cat > file.r 1 + 2 * ( 3 - 4 ) % rlab file.r -1 </PRE> </CODE></BLOCKQUOTE> To exit Rlab type: <CODE>quit</CODE> or <CODE>Ctrl-d</CODE> at the prompt. <H3>On-Line Help</H3> On-line help offers condensed versions of the reference pages for each function, and brief discussion of the major concepts needed to run rlab. A listing of the available help topics is obtained by typing: <CODE>help</CODE> at the prompt. If, for example, you want help with the <CODE>eig</CODE> function, you would type: <CODE>help eig</CODE>. The help system is simple by design. Each help topic or subject is merely a text file, which is displayed to the terminal when requested. This simplicity makes it correspondingly easy for users to add to or modify the help system. If you find something in particular that is missing, or is peculiar to your installation of rlab, you can easily add to the help by creating a file, and placing it in the rlab help directory. <H3>Error Messages</H3> Two types of error messages occur when executing rlab programs: syntax errors, and run-time errors. Syntax errors are a result of the parser's inability to make sense out of the input. When a syntax error occurs, rlab will issue an error message, and identify the syntax error. <BLOCKQUOTE><CODE> <PRE> > (1 + 2)) syntax error (1 + 2)) ^ </PRE> </CODE></BLOCKQUOTE> In the previous example, the error message identifies the extra right parentheses as the offending character. Sometimes that syntax error does not appear to make sense, for example: <BLOCKQUOTE><CODE> <PRE> > ((1 + 2) syntax error ((1 + 2) ^ </PRE> </CODE></BLOCKQUOTE> The error message identifies the right parentheses as the error. But, most of us would think one of the left-parentheses is the error. Actually, it is the lack of a second right-parentheses that is the error. Rlab has a very precise definition of the language syntax and semantics that do not always make sense to the user. Run-time errors occur when a program, with legal syntax, tries to perform an illegal operation. For example: <BLOCKQUOTE><CODE> <PRE> > a + 2 Entity types: Undefined and Matrix_Dense_Real ERROR: rlab2: addition operation not supported </PRE> </CODE></BLOCKQUOTE> This expression is valid, except in this context <CODE>a</CODE> is undefined. The error message tries to tell us this by saying that the addition cannot operate on <CODE>Undefined</CODE> and <CODE>Matrix_Dense_Real</CODE> types. With either type of error execution will halt. If you are running Rlab interactively, execution will return to the prompt. If Rlab is running batch, then the process will terminate. <H2><A NAME="ss1.4">1.4 Migrating From Rlab1 to Rlab2</A></H2> Moving from Rlab1 to Rlab2 is not very difficult. Most of the changes between the two versions are internal to facilitate simpler addition of new data-objects, and better memory management. However, there are a few noteworthy changes made. These changes make programming safer for all levels of users, and are a result of extensive user feedback. <OL> <LI> So that users may keep Rlab1 installed on their computer, Rlab2 is called <CODE>rlab2</CODE>, and the rfiles, help-files, etc are kept in a separate directory hierarchy. A separate path environment variable is required to make this work. <CODE>RLAB2_PATH</CODE> replaces <CODE>RLAB_SEARCH_PATH</CODE>. You should keep both variables in your environment if you have both Rlab1 and Rlab2 installed. </LI> <LI> The most significant change is with the way function arguments are handled by the interpreter. In Rlab-1 function arguments were passed by reference. In Rlab-2 function arguments are passed by value. One of the reasons I used pass by reference in Rlab-1 was efficiency. Many pass by value schemes copy a function's arguments prior to passing execution to the function body. If the function does not modify the arguments, then the copy was un-necessary. The internal design of Rlab-2 allows function arguments to be passed by value without un-necessary copies. If the function does not modify an argument, then the argument is not copied. Only arguments that are modified are copied. My experience with many users is that very few actually take advantage of pass by reference, and a great many are ``safer'' if pass by value is the default. Rlab-1 programs that don't take special advantage of pass by reference (the great majority) will work fine with Rlab-2. </LI> <LI> Rlab2 uses a garbage collector for memory management. This means you can forget about memory-leaks! It also means performance is better. </LI> <LI> Most all of the rfiles have been re-vamped. Not because they needed it. Most (99%) of Rlab1 rfiles will run without modification in Rlab2. The only Rlab1 files that won't work correctly are the ones that rely upon function argument pass-by-reference. My experience tells me that this is very, very few rfiles. An example of modified rfiles are show(), and who() that take advantage of subtle, but new features in Rlab2. </LI> <LI> read() and write() only work in binary now. They still offer a good degree of Matlab compatibility. readb(), and writeb() are still there, but function the same as read() and write(). ASCII read and writes can still be done with readm(), and writem(). If there is a demand for the old read()/write(), I will restore them. </LI> <LI> Sparse real and complex matrices. These are brand new. The implementation is still not complete. The matrix assignment, partitioning, <CODE> +, -, *</CODE> operations are functional. But, there is still lots to do here before they are "seamlessly" integrated with the rest of the classes. </LI> <LI> The help directory/files have been modified. This manual, and the online help files originate from the same SGML sources. There is also an HTML version of this manual for those who want to get at online help that way. </LI> </OL> <H2><A NAME="ss1.5">1.5 Document reproduction and errors</A></H2> The Rlab Reference Manual is freely available. Permission is granted to reproduce the document in any way providing that it is distributed for free, except for any reasonable charges for printing, distribution, staff time, etc. Direct commercial exploitation is not permitted. Extracts may be made from this document providing an acknowledgment of the original SGML source is maintained. Reports of errors and suggestions for improvement in this document in Rlab itself are welcome. Please mail these to <CODE>rlab-list@eskimo.com</CODE>. <H2><A NAME="ss1.6">1.6 Acknowledgments</A></H2> The availability of ``free'' software, such as GNU Emacs, GNU gcc, gdb, gnuplot, Plplot, and last, but certainly not least, the Netlib archives has made this project possible. The Rlab author thanks both the authors and sponsors of the GNU, LAPACK, RANLIB, FFTPACK, and Plplot projects. Many individuals have contributed to Rlab in various ways. A list of contributors can be found in the source distribution file <CODE>ACKNOWLEDGMENT</CODE>. A special thanks to Phillip Musumeci who has tirelessly provided a ftp-site for many years, and co-authored the original RLaB Primer. Matthew Wette who has also provided ftp-sites so that Rlab is available in the U.S.A. Special thanks are also due to Tzong-Shuoh Yang who did the original Macintosh port, and has provided many rfiles, and to Maurizio Ferrari who has ported Rlab to the RISC-OS (Acorn) platform, and to Karl Storck for improving and maintaining the Gnuplot interface. <HR> <IMG SRC="prev.gif" ALT="Previous"> <A HREF="rlab-ref-2.html"><IMG SRC="next.gif" ALT="Next"></A> <A HREF="rlab-ref.html#toc1"><IMG SRC="toc.gif" ALT="Contents"></A> </BODY> </HTML>