Next Previous Contents

1. Introduction

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 ...

1.1 Background

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.

1.2 Installation

Overview

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:

  1. SCO Unix
  2. UnixWare
  3. Linux, both a.out and ELF
  4. SunOS-4.1.x
  5. Solaris 2.x
  6. SGI Irix
  7. HP-UX 9.0x
  8. AIX 3.2.x
  9. DEC Ultrix 4.x
  10. Digital Unix (OSF v2.x on an Alpha)
  11. Acorn RISC-OS
  12. DOS (DJGPP)
  13. OS/2
  14. Mac-OS

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.

Quick Install

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/

  1. Download the necessary files:
    1. The Rlab source code: http://rlab.sourceforge.net

  2. Build Rlab, do:
    1. gunzip rlab.tgz
    2. tar -xvf rlab.tar
    3. ./configure
    4. make
    5. make check
    6. make install

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 PROBLEMS file contained in the Rlab source distribution.

Detailed Installation

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: searleir@yahoo.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:

core sources

RLaB scanner, parser, compiler, virtual machine, and object interfaces.

required Fortran libraries

BLAS:

basic linear algebra subroutines.

LAPACK

linear algebra package

FFTPACK

Fast Fourier Transform package.

RANLIB

Random number and distribution library.

MINPACK

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:

Graphics

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.

Dynamic-Linking

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.

SuperLU

The SuperLU package is a library for direct factorization of large sparse matrices using a supernodal technique. not implemented yet

UMFPACK

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

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.

Garbage-Collection (GC)

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.

Using a Fortran Compiler

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.

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:

--prefix=dir

dir is the root directory where Rlab, and its support files will be installed. Without user intervention dir defaults to /usr/local/lib.

--with-LIBS=dir

dir is a directory where configure should look for libraries. This could be /usr/local/lib on many systems.

--with-NALIBS=dir

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.

--with-FLIBS=dir

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.

1.3 Getting Started

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

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.

Error Messages

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.

1.4 Command Line Options and Environment

Running Rlab2

Rlab is typcially invoked (the biggest exception is the Apple Macintosh version) from the command line with the following syntax:

rlab2 [-Vdhlmnpqr] [file(s)] [-]

Command Line Options

-V

Prints the version number to stderr and exits.

-d

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.

-h

Prints the usage message to the screen and exits.

-l

Prevents loading of the rlab library of rfiles.

-m

Prevents printing of the greeting message.

-n

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.

-p

Prevents rlab from using the specified pager for all output.

-q

Prevents loading of the startup file.

-r

Prevents usage of the GNU readline library for command line editing.

file(s)

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.

Rlab Environment

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.

RLAB2_RC0

The startup file.

RLAB2_HELP_DIR

The principle directory of help files.

RLAB2_LIB_DIR

The directory of rfiles to load on startup.

RLAB2_PAGER

The screen/terminal pager to use.

RLAB2_PATH

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.

RLAB_HISTFILE

The name of the file to store the command history in. The default is .rlab_history.

RLAB_HISTSIZE

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: # Set the RLAB2_PATH env var.  This provides a auto path to the most
 29: # commonly used rfiles.  You can overide this value by setting RLAB2_PATH
 30: # in your environment prior to running rlab2
 31: #
 32: 
 33: if test -z "$RLAB2_PATH" ; then
 34:   RLAB2_PATH=".:$RD/rlib:$RD/toolbox:$RD/controls-toolbox:$RD/examples"
 35: fi
 36: 
 37: #
 38: # The RLaB2 startup script.
 39: #
 40: 
 41: RLAB2_RC0="$RD/.rlab"
 42: 
 43: #
 44: # The RLaB2 Library directory.
 45: #
 46: 
 47: RLAB2_LIB_DIR="$RD/rlib"
 48: 
 49: #
 50: # The RLaB2 help directory
 51: #
 52: 
 53: RLAB2_HELP_DIR="$RD/doc/help"
 54: 
 55: #
 56: # The pager to use.
 57: #
 58: 
 59: RLAB2_PAGER="more"
 60: 
 61: #
 62: # Export the shell environment variables so the RLaB process can
 63: # access them.
 64: #
 65: 
 66: export PATH RLAB2_PATH
 67: export RLAB2_RC0
 68: export RLAB2_LIB_DIR
 69: export RLAB2_HELP_DIR
 70: export RLAB2_PAGER
 71: 
 72: #
 73: # Setup the environment to handle PGplot if necessary.
 74: #
 75: 
 76: if test "$PLOT_PROG" = "pgplot" ; then
 77:   PGPLOT_XW_WIDTH="0.5"
 78:   PGPLOT_FONT="$PLOT_DIR/pgplot/grfont.dat"
 79:   PGPLOT_DIR="$PLOT_DIR"
 80:   LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$PGPLOT_DIR"
 81: 
 82:   export PGPLOT_XW_WIDTH
 83:   export PGPLOT_FONT
 84:   export PGPLOT_DIR
 85:   export LD_LIBRARY_PATH
 86: fi
 87: 
 88: #
 89: # Finally, run RLaB...
 90: #
 91: 
 92: $RLABEXE $*
 93: 

1.5 Migrating From Rlab1 to Rlab2

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.

  1. So that users may keep Rlab1 installed on their computer, Rlab2 is called 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.
  2. 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.
  3. Rlab2 uses a garbage collector for memory management. This means you can forget about memory-leaks! It also means performance is better.
  4. 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.
  5. 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 ASCII read()/write(), I will restore them.
  6. Sparse real and complex matrices. These are brand new. The implementation is still not complete. The matrix assignment, partitioning, +, -, * operations are functional. But, there is still lots to do here before they are "seamlessly" integrated with the rest of the classes.
  7. 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.

1.6 Document reproduction and errors

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 searleir@yahoo.com.

1.7 Acknowledgments

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.


Next Previous Contents