PsiLAB and PsiLAB2 Introduction and Tutorial
Version 1.0/2.0ce

Stefan Bosse
sbosse@physik.uni-bremen.de

1   About this document



This document is an introduction to PsiLAB and PsiLAB2 , the cutting edge version of PsiLAB . Also, compiling from source code and installation is described in detail. Features only available in the cutting edge version PsiLAB2 are explicitly marked.

2   Introduction



2.1   What is PsiLAB

PsiLAB has been developed for scientific research and data analysis. It is freely distributed in source code format under Gnu Public License, version 2.

PsiLAB is written mainly in the functional language O'CA ML developed at INRI research laboratories. It's mainly made of three parts:

  1. An interpreter, of course O'CA ML itself,
  2. libraries written in O'CA ML ,
  3. external libraries written in Fortran and C.
Main features of PsiLAB are:

and all glued in one application.

PsiLAB uses the following external libraries, mainly written in Fortran:

PsiLAB is not only written in O'CA ML , it is CA ML . That means: if you are familar with this programming language, you can write PsiLAB programs. And you can do all things with PsiLAB you can do with the generic O'CA ML development system:

The CA ML interpreter system, which is in fact a pure compiler concept, was chosen because of the high computation speed of this system and the high portability. You have the advantages of an interpreter like language (from the user point of view), but with performance comparable with C/C++ programs. All functions will be translated by the CA ML compiler into a system and machine independent byte code. This byte code will be than executed on a virtual machine.

Currently, you have a terminal driven environement with online help. Plots are printed to an additional X11 window or to a postscript file.

3   Installing PsiLAB . System Requirements



PsiLAB is distributed in source code format. Binaries for several popular UNIX- X11 systems are also available:

Installation requierements:

3.1   Compiling from the source code

You need O'CA ML version 3.01 or 3.02, already installed on your system. PsiLAB2 doesen't need an external O'CA ML distribution. It is shipped with his own version of O'CA ML , silghtly modified from the official release, and with some significant modification, especially enhanced debug and tracing features. The GNU cc compiler and some GNU utils, like gmake are expected. A non GNU environment may perhaps work, too. PsiLAB contains thousands of fortran files. All fortran files are translated with an own version of f2c, and compiled with the system C compiler.

Steps to get a compiled PsiLAB distribution:

  1. Choose a place to unpack the source archive, unpack archive, for example this way:

    tar -zxvf psilab-1.0-src.tgz 
  2. change to the source directory and choose one of the system Makefiles closes to your operating system, and copy this to Makefile.sys, for example

    cp Makefile.sys.freebsd Makefile.sys 
  3. Edit this system dependent Makefile, and change at least the TOPDIR and the INSTALLDIR variables, for example:

    TOPDIR = /home/user/psilab-1.0  
    INSTALLDIR = /usr/local/psilab 
     
    If your system doesen't provide a BSD compatible install script, change the INSTALL variable to:

    INSTALL = $(TOPDIR)/install.sh 
     
    Don't forget to determine your O'CA ML version and set the Makefile variable:

    CAMLVERSION = 3.01 or 3.02 
  4. Probably, some pathes or program names must be changed, too. For machine architectures different from i386, some more changes must be done. Some fortran libraries need machine dependent constants, provided in external fortran files. The system Makefile tells about the locations in the source tree.
  5. Now, start the compilation:

    gmake clean 
    gmake all 
    gmake install 
     
    The last step installs the compiled distribution in the desired directory.
Steps to get a compiled PsiLAB2 distribution are similar. Differences:

  1. The system dependent Makefile also conatins the configuration for the built in O'CA ML distribution.
  2. Some more hand made work must be done: first change to the ocamlsrc directory and compile the O'CA ML compiler system:
     
    gmake core 
    cp ocamlc boot 
    cp byterun/ocamlrun boot 
    gmake all 
    gmake install
  3. Now perform the steps described above and compile the PsiLAB system.

4   Documentation



Available are this document you are currently reading, and the reference manual derived from the online help system.

5   Tutorial



5.1   Getting started

PsiLAB is started by running the Psilab script (first letter is uppercase!). This shell script do an inital environment setup for the psilab binray. This program is a byte code binary, and therfore needs the virtual runtime system called psilabrun, all found in the PSILAB/bin directory. You will immediatley get the start prompt of PsiLAB :




     ===========

     P s i L A B

     =========== 
   Version 1.0 (Sep 26 2001) 
   Written by Stefan Bosse

   sbosse@physik.uni-bremen.de 
   Loading initial environment...Ready. 
[]




You can edit the command line with the cursor keys and the backspace key. A return skips to the next line of your command, and not finishes the command. To mark the end of a command, like in the generic CA ML interpreter, you must put two semicolons at the end for your command:




[] let a = 3.0 ;;

val a : float = 3

[] let a =

   3.0 ;;

val a : float = 3

[]




In this first example you can see the most used CA ML command let. The let command assigns a value or a function (which can perhaps immediatley evaluated) to the new functional name a. This is a constant and is of course immutable and can be used through your further code. But not only constant values can be assigned, you can define new functions this way:




[] let square = fun x -> x**2.0;;

val square : float -> float = <fun>

[] square 2.0 ;;

- : float = 4

[] square a ;;

- : float = 9




Note that CA ML doesen't use brackets around function arguments!

5.2   Matrix operations

PsiLAB comes with an extensive matrix package with low and high level funtcions for creating, manipulating and accessing matrices. The following data types are supported:

integer [ native system integer length]

float [double precision]

complex [double precision]
An Integer matrix can be created with the imatrix function, a float matrix with fmatrix, and complex matrices with the cmatrix function. See the reference manual for details. For example, if you want to allocate a float vector of length 100, use




[] let vec = fmatrix ~dim[100] () ;;

val vec : (float, '_a, '_b) Matrix.t = <abstr>




Don't forget the last unity operator (). You can store new values to matrix elements with the assign operator <- :




[] vec.{10} <- 1.0 ;;

- : unit = ()




You can extract the value of a matrix element simply with:


[] let a = vec.{10} ;;

val a: float = 1




Of course matrices with more than 1 dimension can be handled the same way:




[] let fmat = fmatrix ~dim:[50;50] () ;;

val fmat : (float, '_a, '_b) Matrix.t = <abstr>




The first index of this matrix determines the row number, the second the column number.




[] let row = 10 ;;

[] let col = 11 ;;

[] fmat.{row,col} <- 13.45 ;;

[] fmat.{10,11} ;;

- : float = 13.45




Note: all matrix indices start with number 1!

5.3   Plotting

Several plotting functions are provided.

5.3.1   2D Plot

To plot datasets of one independet variable y(x), or functions of one independent variables f(x), use the plot2d function. Both, datasets and functions, can be plotted in one frame. For example




[] let ydat = fmatrix ~dim:[20] ~rand:[1.0] () ;;

[] let xdat = fmatrix ~fill:[1.0;20.0] () ;;

[] plot2d ~x:[x] ~y:[y] ~title:``Testplot''

   ~xlabel:``X'' ~ylabel:``Y''

   ~xrange:[0.0;20.0] ~yrange:[0.0;1.0]() ;;




leads to the following graphical output:









The plot2d functions is called with several arguments beginning always with a ~ character. This character is needed always for named arguments, so called labels. The ~xrange and ~yrange arguments are optional. They set the axis ranges independently from the minimum and maximum of the x and y values. The ~title, ~xlabel and ~ylabel arguments are used to set the title and axis text labels. There are many more arguments controlling the way the plot is performed. See the reference manual for more details. Now we want to add a function plot:




[] let ydat = fmatrix ~dim:[20] ~rand:[1.0] () ;;

[] let xdat = fmatrix ~fill:[1.0;20.0] () ;;

[] let fun1 = fun x -> sin x ;;

[] plot2d ~x:[x] ~y:[y] ~func:[fun1]

   ~title:``Testplot''

   ~xlabel:``X'' ~ylabel:``Y''

   ~xrange:[0.0;21.0] ~yrange:[-1.2;1.2]() ;;




leads to this plot graphic:












This document was translated from LATEX by  HEVEA