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:
I hope you find it useful ...
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.
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:
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, and numerical functions. The biggest portability problems arise when trying to get the data-visualization (graphics) working. Gnuplot is probably the most portable. Additionally, there are PlotMTV, Plplot, and PGraf graphics capabilities.
This section will present the most basic of Rlab installations, as
briefly as possible. The assumptions are that everything will be
installed in /usr/local, you have an ANSI-C compiler, a
Fortran-77 compiler, and are not interested in graphics (yet).
Don't let the requirement for a Fortran-77 compiler bother you. A decent Fortran-77 (f77) compiler can be easily acquired as part of the EGCS compiler suite. See http://egcs.cygnus.com/
You can also get this files (with similar names) at:
ftp://mirriwinni.cse.rmit.edu.au/pub/rlab
gunzip rlab.tgztar -xvf rlab.tar./configuremakemake checkmake installAt 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 PROBLEMS file contained in the Rlab source
distribution.
This section provides significantly more detail and discussion than the Quick Installation Section. First a note about installation and packaging philosophy. Rlab is now bundled together with the sources for every required package that it uses. Package size is not the problem it was when I first started distributing Rlab (1989). Moreover, some of the required packages (like FFTPACK) are special double precision versions that many people have trouble finding. The last obstacle to bundling the required packages was the poor availability of Fortran-77 compilers; with the advent of the EGCS compiler suites (including g77), this is no longer a problem. So, from version 2.1.00 on Rlab comes with the required Fortran libraries, and the configure and Makefile support to build them automatically.
With an ANSI-C and Fortran-77 compilers available, the
configuration, build, and installation of Rlab is almost completely
automatic. The one area that cannot be automated (if you know
otherwise please contact me: ians@eskimo.com) is
determination of the C-language to Fortran-77 type mapping. Type
sizes in C can (and are) determined automatically but, there is no
equivalent to the C-language sizeof() in Fortran-77. Thus,
the one place a user might have to intervene is to edit the
typedef statements at the bottom of fi.h. To
successfully edit this file you need to know the byte sizes of
Fortran's INTEGER, REAL, and DOUBLE
types. Building Rlab on most modern (i.e. 32 bit flat memory)
systems will not require editing fi.h.
Rlab consists of a core set of source code, certain required Fortran libraries, and a set of optional libraries and programs:
RLaB scanner, parser, compiler, virtual machine, and object interfaces.
basic linear algebra subroutines.
linear algebra package
Fast Fourier Transform package.
Random number and distribution library.
Package for solving nonlinear equations and nonlinear least squares problems.
A fully functional Rlab installation can consist of many parts. So, we will descri 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:
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.
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.
The SuperLU package is a library for direct factorization of large sparse matrices using a supernodal technique. not implemented yet
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).
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.
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.
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.
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:
The Basic Linear Algebra Subroutines provide services for almost all of the other numerical subroutines.
ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rblas.tar.gz
The Linear Algebra PACKage provides the majority of linear algebra functionality for Rlab.
ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rlap.tgz
Fast Fourier Transform PACKage provides the discrete Fourier transform and inverse transform capability.
ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rfft.tgz
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.
ftp://ftp.eskimo.com/u/i/ians/rlab/sources/rnlib.tgz
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 ( ftp://netlib.att.com/)
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 ./configure. Under
more normal circumstances you may need to give configure some help
finding libraries, etc. Some of the most commonly used configure
options are:
dir is the root directory where Rlab,
and its support files will be installed. Without user
intervention dir defaults to /usr/local/lib.
dir is a directory where configure
should look for libraries. This could be /usr/local/lib
on many systems.
dir is a directory where
configure should look for numerical analysis
libraries. Specifically, configure looks for libClapack,
libCblas, libCfftpack, and
libCfftpack. 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.
dir 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.
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:
$ 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
>
The > 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:
> "Hello World"
Hello World
Rlab echoes its input, unless it is directed not to. To silence Rlab
end each statement with a ;
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.
% cat > file.r
1 + 2 * ( 3 - 4 )
% rlab file.r
-1
To exit Rlab type: quit or Ctrl-d at the prompt.
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: help at the prompt. If, for example, you want help
with the eig function, you would type: help eig.
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.
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.
> (1 + 2))
syntax error
(1 + 2))
^
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:
> ((1 + 2)
syntax error
((1 + 2)
^
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:
> a + 2
Entity types: Undefined and Matrix_Dense_Real
ERROR: rlab2: addition operation not supported
This expression is valid, except in this context a is
undefined. The error message tries to tell us this by saying that
the addition cannot operate on Undefined and
Matrix_Dense_Real 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.
Rlab is typcially invoked (the biggest exception is the Apple Macintosh version) from the command line with the following syntax:
rlab2 [-Vdhlmnpqr] [file(s)] [-]
Prints the version number to stderr and exits.
Causes a readable form of the internal stack
machine's compiled program to be output to
stderr. This option should be used in conjunction
with -qln options. This option is not intended
for general use.
Prints the usage message to the screen and exits.
Prevents loading of the rlab library of rfiles.
Prevents printing of the greeting message.
Prevents line number and file name information from
being used in the internal stack machine codes. This
option should only be used with the
-dlnq. This option is not intended for general
use.
Prevents rlab from using the specified pager for all output.
Prevents loading of the startup file.
Prevents usage of the GNU readline library for command line editing.
are loaded and executed by rlab after the `.rlab' file, and after the library files.
Forces rlab to go interactive after all the files on the command line have been executed.
Typically, when Rlab is built (compiled) knowledge of the installation directory paths is built-in to the executable. However, these default settings can be supplanted with alternate definitions via the following environment variables.
The startup file.
The principle directory of help files.
The directory of rfiles to load on startup.
The screen/terminal pager to use.
A colon separated list of directories to
search when attempting to load rfiles. This directory
list should contain the RLAB2_LIB_DIR and the
Rlab toolbox directory.
The name of the file to store the command
history in. The default is .rlab_history.
The length of the command history. The default is 128.
Overriding the compiled-in definitions can happen at the system level (for all users), or on a user-by-user basis, to accomodate individual customizations. A good example is the Bourne-shell script (normally contained in ./misc/rlab) that sets each environment variable so that a pre-compiled binary can be used on a system with a different installation directory.
1: #!/bin/sh 2: 3: # 4: # A simple Bourne-shell script to run RLaB2 from any installed location. 5: # To get RlaB2 working you only need to modify the first 6: # shell variable. 7: # 8: 9: # 10: # Modify the following to identify where the RLaB2 "root" 11: # directory is... 12: # 13: 14: RROOT="rlab_exec_prefix" # Where the rlab directory is. 15: RLAB_VER="rlab_ver_string" 16: PLOT_DIR="plot_dir" 17: PLOT_PROG="plot_prog" 18: 19: # 20: # Do _not_ modify the next two definitions... 21: # (unless you are sure of what you are doing). 22: # 23: 24: RD="$RROOT/lib/rlab2" # The parent rlab library directory. 25: RLABEXE="$RROOT/bin/rlab-$RLAB_VER" # The rlab executable. 26: 27: # 28: # You may want to modify RLAB2_PATH, or define your own 29: # RLAB2_PATH, which will get modified here... 30: # I suggest doing this after you have run RLaB 31: # and are a little familar with it. 32: # 33: 34: RLAB2_PATH=".:$RD/rlib:$RD/toolbox:$RD/examples:$RLAB2_PATH" 35: 36: # 37: # The RLaB2 startup script. 38: # 39: 40: RLAB2_RC0="$RD/.rlab" 41: 42: # 43: # The RLaB2 Library directory. 44: # 45: 46: RLAB2_LIB_DIR="$RD/rlib" 47: 48: # 49: # The RLaB2 help directory 50: # 51: 52: RLAB2_HELP_DIR="$RD/doc/help" 53: 54: # 55: # The pager to use. 56: # 57: 58: RLAB2_PAGER="more" 59: 60: # 61: # Export the shell environment variables so the RLaB process can 62: # access them. 63: # 64: 65: export PATH RLAB2_PATH 66: export RLAB2_RC0 67: export RLAB2_LIB_DIR 68: export RLAB2_HELP_DIR 69: export RLAB2_PAGER 70: 71: # 72: # Setup the environment to handle PGplot if necessary. 73: # 74: 75: if test "$PLOT_PROG" = "pgplot" ; then 76: PGPLOT_XW_WIDTH="0.5" 77: PGPLOT_FONT="$PLOT_DIR/pgplot/grfont.dat" 78: PGPLOT_DIR="$PLOT_DIR" 79: 80: export PGPLOT_XW_WIDTH 81: export PGPLOT_FONT 82: export PGPLOT_DIR 83: fi 84: 85: # 86: # Finally, run RLaB... 87: # 88: 89: $RLABEXE $* 90:
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.
rlab2, and the rfiles, help-files, etc are
kept in a separate directory hierarchy. A separate path environment
variable is required to make this work. RLAB2_PATH replaces
RLAB_SEARCH_PATH. You should keep both variables in your
environment if you have both Rlab1 and Rlab2 installed.
+, -, * operations are functional. But, there
is still lots to do here before they are "seamlessly" integrated
with the rest of the classes.
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
rlab-list@eskimo.com.
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
ACKNOWLEDGMENT. 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.