File: /home/csi/mlab/readme.linux Revision Date: Sep 24, 2015 =================================================================== MLAB Installation and Operation Guide This is the installation guide for the downloaded 32-bit or 64-bit Intel Linux versions of MLAB. The only difference between these two versions of MLAB is that the 64-bit Linux MLAB only runs on a 64-bit Linux operating system, while the 32-bit Linux MLAB runs on either a 64-bit or 32-bit Linux operating system. (The 32-bit MLAB running on a 64-bit system requires certain 32-bit dynamically loaded modules which should be present, but might not be!) Versions of MLAB also exist for Windows 95/98/NT/2000/XP/Vista/Win7/Win8, DOS 640K overlay, DOS extended-memory flat model, 16-bit Windows 3.1, Intel Macintosh OS-X, PowerPC Macintosh OS-X and OS-9, Motorola Macintosh OS8, and several UNIX versions. The MLAB system as downloaded has all the powers of full MLAB, but with a limited lifetime until it is registered with Civilized Software. There are manuals available for MLAB from Civilized Software. These are: MLAB Reference Manual MLAB Applications Manual MLAB Graphics Examples MLAB Users Guide All these manuals are available as pdf-files at www.civilized.com. The first three can be provided in printed form for $99 plus shipping from Civilized Software, Inc. These books are much more up-to-date and complete than is the on-line help file available in MLAB by typing `HELP', which might be your main source of information aside from this document and studying the example do-files provided with MLAB. PDF-file representations of the MLAB Reference Manual and the MLAB Applications Manual can be downloaded for free from the Civilized Software website, www.civilized.com. You should print these manuals for easy access to their contents. It is important to have a copy of the MLAB Reference Manual, since there are hundreds of useful functions in MLAB that are only defined in the MLAB Reference Manual. MLAB Installation Instructions for Intel(32-bit) Linux Systems -------------------------------------------------------------- MLAB is a mathematical modeling system with facilities for curve fitting, differential equation solving, linear algebra, statistics, and 2D and 3D graphics. For Intel-Linux, the graphics facilities are based on X-Windows. MLAB is available from Civilized Software 12109 Heritage Park Circle Silver Spring, MD 20906 phone: (301) 962-3711 web: www.civilized.com email: csi@civilized.com The usual way to get MLAB is to download a copy from www.civilized.com and install it on your PC. LICENSING By installing MLAB, you agree to not use any parts of the MLAB files or manuals, modified or unmodified, as parts of any commercial products without permission. You agree to register and use MLAB on one computer per license purchased. INSTALLATION OVERVIEW MLAB installation on your Intel-Linux PC consists of two steps: a. Obtain the lmlabtar64.gz or lmlabtar32.gz distribution file by downloading it from www.civilized.com. b. Install the MLAB files on your system and set the appropriate environment variables (PATH) and configuration options. You will need to select a directory to store the subdirectories which hold the MLAB executable file and the other files that make up the MLAB system. These subdirectories are: bin/, lib/mlab/, and lib/mlab/examples/. The "system" directory /usr/local is recommended, because then MLAB can be easily run by any user. The MLAB files will then be installed in various subdirectories as tabulated below. The files that make-up the MLAB system are: ------------------------------------------------------------------ In the ./bin/ directory: mlab executible script for running MLAB MLAB executible script for running MLAB In the ./lib/mlab/ directory: LMLAB.README (this file) INIT0.FIL the secondary MLAB initialization file TOKEN.FIL the MLAB token file DW.SAV the MLAB defaultwindow save file INIT.SAV the MLAB initialization file MLAB.HLP the MLAB help text file gxfonts.0 the MLAB stroke font file gxserver the expose-event-handler executable program dimer.do an example MLAB do-file for study startup.do an automatic demonstration do-file startup.dat a data file for startup.do mlab the MLAB executable program examples/ sub-directory with various do-files. In the ./lib/mlab/examples directory are 27 do-files for study and tutorial use: mlabex.do mlabex1.do windkex.do kmestex.do hhdoex.do dimerex.do holfex.do enzymex.do gcrex.do payex.do liglex.do ttestex.do vorex.do centriex.do dcaex.do djiaex.do snsptex.do laserex.do conex.do ctnryex.do henonex.do minmodex.do ndiskex.do magnetex.do torex.do lrcex.do fnpex.do plus, 10 dat-files (data files) used by the tutorial do-files: kmestex.dat gcrex.dat a3azt.dat recssd.dat recssm.dat divisor.dat sunspots.dat slm.dat test.dat molex.dat The protection codes for these files are tabulated below. Subdirectory (of /usr/local) Files (protection codes) ------------------------------------------------------------------ ./bin mlab (555) MLAB (555) ./lib/mlab DW.SAV (644) INIT.SAV (644) INIT0.FIL (666) MLAB.HLP (444) TOKEN.FIL (444) gxfonts.0 (444) gxserver (555) mlab (555) startup.do (644) startup.dat (644) LMLAB.README (644) df.bin (666) ./lib/mlab/examples 27 example do-files and 10 example dat-files (all protection codes are 644) ------------------------------------------------------------------ You MUST have the proper UNIX permissions to create and write into the MLAB installation directory. You should be running as "root" when you 'untar' MLAB, since you will probably be installing MLAB in a write-protected system directory like /usr/local, which allows all users access to MLAB. You can also install MLAB in your home directory or any other directory for which you have write-permission, however, you must make certain specific modifications when you install MLAB anywhere other than /usr/local/. MLAB provides associated MLAB shell script files which are placed in an appropriate directory (usually /usr/local/bin). (These shell scripts are named MLAB and mlab.) They contain the shell commands needed to run MLAB. (These shell scripts refer to the /usr/local/ directory. You will need to change them if you install MLAB elsewhere.) If the bin/ directory holding the MLAB shell script files is not on your path, you should put it there after installing MLAB! You can do this by appropriately editing your shell initialization script, for example .login for sh, .cshrc for csh, .bashrc for bash, etc. and adding /usr/local/bin to your path. (And if you install MLAB in a directory other than /usr/local/ then you will want to modify your PATH environment variable accordingly.) SYSTEM ADMINISTRATION STEPS If you must have superuser (root) access to the operating system when you install MLAB. (If you do not have write access to the directory that contains the MLAB files (usually /usr/local), MLAB cannot be installed.) You can also do the required operations by prefixing them with sudo. Also, before you try to install MLAB you need to have set-up your system so you may run an X-Windows server and a terminal emulator window. This mainly includes setting the DISPLAY environment variable for each MLAB user. (This has probably already been done, but if not you can do it as follows.) DISPLAY has to be set to the string: machine-name:display-number[.screen-number].(Try running MLAB first, this is probably already set in your environment.) You can check your enviroment variables with the command [env] typed in a text-based login session or in a terminal window. If you need to change DISPLAY, use the command: setenv DISPLAY machinename:0 for csh, tcsh, etc. or export DISPLAY=machinename:0 for sh, bash, etc. Directions to download and install a copy of Linux MLAB You may obtain a copy of Linux MLAB by going to www.civilized.com and following the appropriate links to reach the download link. When you click this link you will obtain a "tarred" file, either lmlabtar64.gz or lmlabtar32.gz, on your hard disk in a directory determined by you and your browser. Be sure to note carefully where the downloaded lmlabtar64.gz or lmlabtar32.gz file is placed. The version of MLAB you will obtain is the complete program with an expiration date. This program will expire after 30+ days unless you purchase MLAB and register this copy (via email to csi@civilized.com.) On-line help is available (by typing "help" in MLAB), and you may order the three MLAB manuals and have them shipped to you by mail (see the offer in the readme.linux file in /usr/local/lib/mlab directory, or on the Order Form page. You may also download the manuals in PDF format from the Manuals page at www.civilized.com. You must follow the directions below to install MLAB. Step 1. Start a "command-line" terminal window. Then create if necessary and cd to the directory which is to contain the MLAB system subdirectories. Usually this is /usr/local/ [It is highly recommended that you cd to /usr/local/ for this installation!]. (Use the command 'mkdir mlabdir' in the desired containing directory to create the directory for MLAB, if you do not use /usr/local/, and use the command 'cd mlabdir' (i.e., 'cd /usr/local' in the default case,) to "enter" the directory where the MLAB files will be placed.) You must have "root-privileges" to install MLAB in /usr/local/. Thus you must either login as root before you begin the installation process, or you must use the command 'sudo' with the tar command below that unpacks the MLAB files in lmlabtar64.gz or lmlabtar32.gz and places them in /usr/local/lib/mlab. Step 2. Type [tar -xvzpof ~~/lmlabtar64.gz] or [tar -xvzpof ~~/lmlabtar32.gz] while logged-in as root, or type [sudo tar -xvzpof ~~/lmlabtar64.gz] or [sudo tar -xvzpof ~~/lmlabtar32.gz]for Debian/Ubuntu-based systems where you do not need to be logged-in as root. (~~ denotes the path to the file lmlabtar64.gz or lmlabtar32.gz) You MUST be in the directory where you want the MLAB files and subdirectories to be placed by cd'ing following step 1. (On older linux systems, you may need to use the command [tar -xvzpof ~~/lmlabtar64.gz .] or [tar -xvzpof ~~/lmlabtar32.gz .] The "." refers to the current directory into which you are installing MLAB.) Of course, in all cases, you must have cd'ed into that directory before you run this command.) !!! Be sure to replace ~~/lmlabtar64.gz or ~~/lmlabtar32.gz with the FULL CORRECT PATH and file-name to the distribution package file you downloaded, (i.e., /lmlabtar64.gz or /lmlabtar32.gz) in the tar command. (You must be root, or you must prefix 'sudo' for this tar command to work when you are installing in the /usr/local directory.) The tar command extracts all the MLAB files and places them in the appropriate subdirectories. This step will take a few seconds. After "un-tarring", all the MLAB files (except the bash-scripts, mlab and MLAB) will be in the directory tree lib/mlab/ in the directory you have chosen to unpack lmlabtar64.gz or lmlabtar32.gz in. (Usually /usr/local). If the lib subdirectory already exists, the mlab subdirectory will be placed within it, otherwise the lib directory will be created by tar first. Step 3. Put the MLAB shell script directory (usually /usr/local/bin) on your 'path' environment variable if it is not already there. Your 'path environment variable' consists of a list of directories separated by ':'s that will be searched whenever you specify an incomplete path for a program that you wish to run. With your path set to include /usr/local/bin, you can run MLAB by typing 'mlab'; otherwise you would have to type '/usr/local/bin/mlab' to run MLAB from a command-line terminal window. You may add /usr/local/bin to your path as follows: (you may print-out the contents of your path with the command [echo $PATH]). If you need to add a directory to your path, (such as /usr/local/bin), use a text-editor to place the following command in your .bashrc file in your home directory. export PATH=$PATH:/usr/local/bin Your .bashrc file (in your home directory) is your "startup" file of bash commands that are executed whenever you run bash. Your .bashrc file is writable by you, thus all you need to do to change it is to run an editor of your choice on that file. Then add the specified command above (with a comment of the form: [# add /usr/local/bin to the path environment string.] and save that changed file back in your home directory. In brief, you install MLAB with the commands: cd /usr/local tar -xvzpof ~~/lmlabtar64.gz (or sudo tar -xvzpof ~~/lmlabtar64.gz) or: tar -xvzpof ~~/lmlabtar64.gz (or sudo tar -xvzpof ~~/lmlabtar32.gz) [add "export PATH=$PATH:/usr/local/bin" to ~/.bashrc with an editor.] You are now ready to use and enjoy MLAB. You run MLAB by typing: 'mlab' in a terminal window. (Typing 'MLAB' (in upper-case) will also work.) Note, however, if you did not use /usr/local/ as the root directory for installing MLAB, the execution scripts, mlab and MLAB in the bin directory, will need to be modified! [Go look at them!] Other Issues Some Linux systems, notably KDE-based systems, use an annoying "security" feature you will need to be aware of. When you log-in, a file called .Xauthority is written to your home directory containing some encoding of your user-name and login session information. When you run a program like MLAB that uses X-windows, this file is checked, and if it is missing or not correct, the program you are running will not be able to use X-windows! The "gotcha" is that if you su to be another user, and then run MLAB, that user's .Xauthority file may be missing, and even if not, will not pass the "security test"! Beware. Another annoying issue is that some "window-managers", again like KDE, have elaborate systems of options controlling their behavior. Specifically, in MLAB when you draw and view a picture, (e.g., a graph,) that picture should appear in a new X-window "in front" of all other windows for you to see. MLAB's request for this to happen will be ignored, (and the window containing the graph may be partially hidden, so that you must click on it to bring it to the front,) unless you set the options of your window-manager properly. (For KDE this means setting "focus-stealing-prevention" to "none". To do this is a very complex operation, but maybe you can figure it out. If not, please email us at csi@civilized.com.) RUNNING MLAB In order to run MLAB, you must first establish an X Windows server and an X-Windows-based UNIX terminal emulator window (e.g. xterm, cmdtool or shelltool, etc.) On almost all Linux systems, all you have to do is run the provided terminal emulator program, accessible in some menu displayed through some icon. (Although it is far easier to have a shell-terminal-emulator icon on your "desktop" and just click or double-click it.) Then you run MLAB by invoking the MLAB shell script, mlab or MLAB. This is done by typing MLAB (or mlab) at the UNIX prompt in the X-terminal window. You can also create an "icon" for the MLAB program and place this icon on the Gnome or KDE or other "Desktop". This icon specifies a small file in your Desktop directory be accessed by the "program-launcher". This file refers to an application program file to be run. When the icon is clicked, this causes the Gnome or KDE or whatever GUI program-launcher program to run that program. In MLAB's case, the icon data also specifies that MLAB is to "launched" in an xterm window.) You will need to consult some Linux sources to find out how to create such a "launch-icon", but basically, it involves interacting with your window-manager program. The first time MLAB is run, it asks you for your username, and then it displays a menu from which you run some examples. (You should do so.) When MLAB is subsequently run, it prints a salutation including the date and time, and displays the start-up menu. After the first day, it asks you to purchase and/or register MLAB if you have not done so. REGISTERING MLAB When you first run MLAB, you will be asked to enter the name of the principal MLAB user, which is recorded so that it may be typed-out each time MLAB is run subsequently. Also, after the first day, you will be asked to register MLAB with Civilized Software. In particular, you will be asked to enter an authorization key-value to register MLAB, or to enter zero if you do not (yet) have your authorization key value. If you have a limited-lifetime version, as you get when you download MLAB from www.civilized.com, you will be prompted to purchase MLAB; following which you can obtain an authorization key and register it. If you have already purchased MLAB, you need to contact Civilized Software at csi@civilized.com to obtain your authorization key-value. If you have not yet purchased MLAB, you need to contact Civilized Software to purchase MLAB. When you enter 0, MLAB will report your "MLAB identifier value", and then proceed to run by displaying the start-up menu (from which you can view some examples of MLAB computations.) Each time you run MLAB, you will be asked for an authorization key value. You may continue to enter 0 for your authorization key-value. You will be able to use MLAB in this manner until it expires, which is generally 30 days or more from your initial installation. At expiration, your MLAB identifier value will still be reported to you, but MLAB will not run after that, until you contact Civilized Software and "trade" your MLAB identifier value for an authorization key-value by purchasing MLAB. MOVING MLAB TO ANOTHER COMPUTER You can install MLAB on as many computers as you wish, but if you want to register MLAB with an unlimited lifetime on a computer that would exceed your licensed number of registered copies, you will be required to uninstall MLAB from an existing registered computer. Directions on how to proceed to uninstall MLAB are as follows. 1. Call or email Civilized Software and notify us that you are moving your registered copy of MLAB to a new machine. 2. Run MLAB on the current machine it is installed on, and enter the command "-INSTALLMLAB" and record the uninstall code that is reported to you. This copy of MLAB is now disabled can not be run after this, unless it is re-registered there. 3. Install MLAB from the diskettes, or via downloading from the web, on the new machine. Run it and obtain the MLAB identifer value for that install. 4. Call or email Civilized Software and report both your uninstall code and the new MLAB identifier value. We will return to you the necessary authorization value for you to register MLAB on this new machine. Please call Civilized Software (301-962-3711); or email us at csi@civilized.com if you have any problems. WHAT MLAB DOES WHEN IT IS RUN After MLAB is registered, you will not be prompted again for an authorization key. In any event, after MLAB is started and prompts you to register MLAB if applicable, and you properly respond, MLAB then executes the MLAB script startup.do found in /usr/local/lib/mlab/. (An MLAB script is called a DO-file. It is essentially an MLAB program.) The DO-file startup.do posts a menu with 3 choices in an MLAB dialog window. The three choices are: 1) run example DO-files corresponding to certain sections in the MLAB Applications Manual, 2) go to top level MLAB, and 3) display some tips on using MLAB. You may now select an option in this menu window by using the up and down arrow keys on the keyboard or clicking the left mouse button while the mouse cursor is on an option; then 'go to' that selection by hitting the Enter key on the keyboard or clicking the left mouse button while the mouse cursor is on the Continue button. Selecting the first option will present a brief summary of how to interact with subsequent example DO-files. Clicking on the Continue button or striking the Enter key for that dialog window will then present a list of example do-files of MLAB commands. Note that one of the options is to present a further list of examples. You can get more information about each of the example do-files by reading the corresponding chapter of the "MLAB Application Manual". (You can also print-out and study the do-files in the examples/ subdirectory.) Selecting the third option of the startup menu will cause MLAB to present some tips on how to get started using MLAB. If you click on the continue button or strike the Enter key, MLAB will then present the menu of example do-files. Selecting the second option of the startup menu will cause MLAB to print an asterisk (*) in the X-Windows-based xterm terminal emulator window. The asterisk is your prompt to type MLAB commands. If you type `help' at the MLAB prompt, MLAB will print a list of topics for which information is available. It is strongly suggested that you run some of the MLAB example do-files that are relevant to the type of problems that you wish to solve and then go to top-level MLAB. You can then scroll back through the commands that MLAB executed and get an idea of what MLAB commands you will be using. Consult the on-line help system, the "MLAB Reference Manual", the "MLAB User's Guide", the "MLAB Applications Manual", and the "MLAB Graphics Examples" for more information. You should also directly print the example do-files found in /usr/local/lib/mlab/examples/ for further study. EXITING MLAB You should exit the MLAB program by typing the command EXIT to MLAB. However, the MLAB program can also be quit by clicking on the close 'control button' (the X in the upper-right-corner) of the xterm window. Generally, a log-file called mlab.log that contains all the MLAB commands that you typed, and all the corresponding output will be written in your working directory. USING DO-FILES You should quickly get in the habit of constructing do-files using your favorite text editor (vi, emacs, etc.). A DO-file is just a "script" containing MLAB commands that can be easily repeated and easily changed. You use a text-editor to prepare or change a do-file and save or re-save it in an appropriate directory of your choice; generally it is convenient for this directory to be you working directory that you cd to before you run MLAB. Basically, you should run two xterm programs. In one, you execute the command "mlab" to run MLAB there. In the other, you run your favorite editor. When you want to build and run a do-file, you then use the editor to construct the do-file text, and then save it in your working directory, say with the name "toy.do". Now you move to the xterm window where MLAB is running (with the same working directory established,) and type the command "do toy" in MLAB to execute the do-file toy.do. You can change the file toy.do by going back to the editor, changing it and saving it back to the disk. You then run the revised do-file by typing "do toy" again in MLAB. By this means, you can converge on a do-file that does what you want. If you do not cd to your desired working directory BEFORE you run MLAB, then you will have to have the MLAB string-variables FILEDIR and DOFILEDIR set appropriately, as described below. HOW TO SPECIFY DIRECTORIES When you run MLAB, you have a "working directory" established. By default this working directory is your "home"-directory when you start an xterm window. In any event, the MLAB string variable "FILEDIR" should be initialized to the character string specifying your desired working directory as described below; it can be changed at will to specify any other directory you may wish to access. If "FILEDIR" is null, then your default working directory determined as specified above will be implied. (Note an alternate way to edit a file is to hold down the Control key and strike the letter Z on the keyboard (i.e. type ^Z); this will suspend the MLAB application and a Unix editor, such as vi or emacs, may then be run in the bash shell running in the xterm terminal window by typing the appropriate command (e.g. emacs filename, or vi filename). To resume the MLAB process after running the vi or emacs editor, type: fg , to resume the MLAB process.) [Currently, ^Z does not work in MLAB.] After you have written a do-file, and saved it in the desired directory, you may execute it by typing: `DO ' in MLAB. You can also type 'DO ' in MLAB to specify that the do-file be read from the specified directory. The FILEDIR string is prepended to every filename referred in MLAB. Thus another way to access a do-file in a specific directory is to specify that directory path by assigning it as a string to the FILEDIR variable. The path to the DO-file must be completely specified via the combination of the supplied filename prepended by FILEDIR in order for the DO-file to be found. Generally it is convenient to store your DO-files in the working directory (as established when MLAB is first run). If there are errors or modifications are to be made in your DO-file, you may then re-edit and re-save the do-file, and return to the MLAB application to execute the do-file again. This is the usual way that MLAB is run for substantial computation. FILEDIR is initially the empty string "" when the first MLAB prompt is shown. (the MLAB string variable, MLABPATH, is initialized to the string "/usr/local/lib/mlab"). Since your usual default working directory is your "home"-directory, you can specify some other directory be used as the MLAB "default"-directory by setting FILEDIR appropriately. The lack of an initial "/" indicates that the contents of FILEDIR is to be appended to the current Unix working directory path in order to determine the final MLAB working directory. MLAB applies the FILEDIR path to (almost) every file it reads and writes, including do-files. There is another string variable, DOFILEDIR, that is to be set to a path (partial or complete) that only applies to files mentioned in the DO command. MLAB FILES During an MLAB session, any of several files may be required or produced: 1. there may be scripts of MLAB commands, called DO-files. The DO-files called MLABINIT.DO and STARTUP.DO, if they exist, are automatically executed each time MLAB runs. Examples of DO-files are included in the directory /usr/local/lib/mlab/examples/. You can create your own DO-files with a text editor as described above. Do-files are executed by typing: DO where is the name of the DO-file. If a file extension is not included in the filename, the extension .DO is appended by default. The following MLAB variables, and associated values, control the execution of the DO-file. You set the value of these variables with ordinary assignment statements, e.g. echodo = 3. - echodo echodo controls where the commands in the DO-file and output are printed as the DO-file is executed. If echodo = 3, each DO-file statement and MLAB response, if any, is printed to the terminal window and written to the file named MLAB.LOG. (See log-files, later.) If echodo = 1, each DO-file statement and MLAB response, if any, is printed only to the terminal window. If echodo = 2, each DO-file statement and MLAB response, if any, is written only to the log-file. If echodo = 0, DO-file statements are neither printed to the screen and nor written to the log-file. - dostep dostep controls the execution of successive statements in the DO-file. If dostep = 0, the DO-file executes without stopping, except where PAUSE, VIEW, KREAD, and other statements requiring user input appear. If dostep = 1, the DO-file executes one statement at a time, waiting for the user to press a key on the keyboard before proceeding to the next statement. - casesw if casesw = 1, then all names used in MLAB commands are case sensitive; i.e. MLAB distinguishes upper case characters from lower case characters in all names of variables, matrices, windows, functions, etc. if casesw = 0, then no distinction is made between upper case and lower case characters. 2. Data in ASCII text format can be read from .DAT files by issuing the MLAB READ command: = READ(,nrows[,ncols]) where is the name of a matrix to which the array of numbers to be read is to be assigned; is the name of an existing file that can be read by the current MLAB user. If no filename extension is included in the filename, then .DAT is appended by default; nrows is an integer that determines the number of rows of scalar numbers to be read from the file; and ncols is an optional integer that determines the number of columns of scalar numbers to be read from the file. For example, M1 = READ(dn,4,3) opens the file dn.DAT, reads 12 floating point numbers from the file dn.DAT, and assigns the 12 numbers arranged in a four row by three column array in row-major order to the matrix named M1. Subsequent READ commands cause numbers to be read from the beginning of the named file. The READON command can be used to open a file and read more than once from the named file without starting from the beginning of the file each time. For example, the first 12 numbers in the file dn.dat are arranged in a four row by three column array and assigned to the matrix named M2, and the next six numbers in the file dn.dat are arranged in a three row by two column array and assigned to the matrix named M3 with the following two MLAB commands: M2 = READON(dn,4,3) M3 = READON(dn,3,2) 3. MLAB data objects may be saved in .SAV-files by issuing the MLAB SAVE command: SAVE [object names] IN where [object names] and filename extension are optional; if [object names] are omitted, all MLAB objects including user-defined variables, functions, matrices, and graphic windows, MLAB system variables in the current MLAB session are saved to the named file. If a file extension is not included in the filename, the extension .SAV is appended to the filename, by default. The objects saved in a file created from an MLAB SAVE command can be restored to an existing MLAB session or a new MLAB session by issuing the command: USE The USE command reads the named file and restores the MLAB data objects in the MLAB application's memory space, printing the name of each object to the screen and log-file as they are read. If name conflicts exist between objects stored in the current MLAB session and objects that are read from the .SAV file, MLAB can optionally rename the objects that are read from the .SAV file to avoid conflicts; MLAB prompts the user when possible conflicts can occur. The file /usr/local/lib/mlab/DW.SAV is a .SAV file provided with the MLAB package that defines the default MLAB graphic window object. 4. ASCII coded versions of data objects for export to other programs called .LST files may be generated by issuing the PRINT command. The MLAB command: PRINT [object names] IN creates the named file, with the extension LST if a file extension is not included in the command. The named objects, such as scalar values, matrix element values, and function definitions, are then printed to the file. The value of the variable PRINTSW controls the printing of identifying strings. If PRINTSW = 1, the names of objects such as scalars and matrices, and matrix row numbers are printed with the values of scalars and matrices. If PRINTSW = 0, only the values, without identifying names are printed. 5. graphics files suitable for printing on PostScript printers called .PS files may be made by issuing a PLOT command. The MLAB command: PLOT [windows] [IN ] creates the named file and writes ASCII text PostScript commands depicting graphs in the named MLAB windows to the named file. If no MLAB window names are provided in the command, PostScript command depictions of all unblanked MLAB windows are written to the file. If a filename is not provided in the command, a file named mlab#.ps, where # is the first integer in the set {1,2,3,...} selected so as to avoid a name conflict with files in the working directory. The MLAB system variable PLOTDEV determines the type of graphics output. By default, PLOTDEV equals PSL and the PLOT command generates files for black and white PostScript output. If PLOTDEV equals PSCL, then the PLOT command generates files for color PostScript output. If PLOTDEV equals HPLJ, then the PLOT command generates files for Hewlett-Packard LaserJet output. If a PostScript or Hewlett-Packard printer driver and lpd printer demon is properly configured, the following Unix command may be used to send the file MLAB0.PS to the printer: lpr MLAB0.PS 6. The MLAB file MLAB.HLP contains descriptions of most MLAB built-in functions and statements. By typing "help" after the MLAB prompt, you will get general information about MLAB, and you can follow the directions to get more specific information. Alternately, you can type: help "topic" where "topic" is a quoted string name of an MLAB built-in function or statement, the corresponding description is read from the MLAB.HLP file and printed to the MLAB terminal window. Unfortunately, the file MLAB.HLP is not complete. Thus you should have a copy of the MLAB Reference Manual to make best use of MLAB. 7. finally, MLAB always creates a log file of all commands and responses in an MLAB session called MLAB.LOG. MLAB0.LOG, MLAB1.LOG, and MLAB2.LOG are the log files for the previous three MLAB sessions. These files will all reside in the directory /usr/local/lib/mlab/ in which the MLAB application file is located, unless the control variables FILEDIR and/or DOFILEDIR are set to specify particular directories. TECHNICAL SUPPORT Please contact Civilized Software (301-962-3711); or email us at csi@civilized.com if you have any problems. INTRODUCTION TO USING MLAB Here is a brief introduction to using MLAB. 1. MLAB as a calculator. ======================== MLAB can be used as a calculator. As with most computer languages, + is used for addition, - is used for subtraction, * is used for multiplication, / is used for division, and ^ is used for exponentiation. Numbers may be entered as integers, floating point numbers with a decimal point, or in scientific notation using the letter E before the exponent. All numbers are converted to 64-bit, double precision, floating point numbers. Note that MLAB does not directly support complex numbers. The precedence of operations evaluated from right to left in an expression, from highest precedence to lowest precedence, is: exponentiation, division, multiplication, subtraction, and addition. Parentheses (), square brackets [], and curly braces {} may be used pairwise to alter the natural order of evaluation. The variable PI is automatically defined in MLAB to be 3.14159265. For example, following the asterisk prompt, type: 6.02E23*1*10/(.0812*276) where means the Enter or Return key on the keyboard, and expect to get back = 2.68615692E23 and another asterisk. This is the number of atoms of an ideal gas in a 10 liter volume at standard temperature and pressure as given by the ideal gas law. In all that follows, we shall omit the , but you should not, because otherwise nothing will happen. If MLAB detects an error in the command, it will display an error message. You may copy the errant command on a previous command line to the system's clipboard, paste the contents of the clipboard to the current command line, and edit the pasted text on the current command line by positioning the text cursor with the mouse or left/right arrow keys and inserting or deleting characters from the keyboard to correct thye errant command. The up/down arrow keys can be used to scroll through the history of typed MLAB commands and re-execute or edit a previously typed MLAB command. ARITHMETIC EXCEPTIONS An important feature of MLAB is that, unlike many systems, "arithmetic exceptions" are detected and handled in a way that allows many computations, such as curve-fitting, to usefully proceed, rather than terminate the computation. In particular, if a "divide-by-zero" occurs, a warning will occur rather than error, and an "appropriate" numerical result will be generated (go try 2/0, -4/0, and 0/0). If an "overflow" occurs, the largest correctly-signed computational value (1.797..E308 or -1.797..E308) will be generated (try: 1.5e167 * (-2.3e201)). Arithmetic exceptions are handled in MLAB by detecting and handling the signals generated by the operating system when such exceptions occur. 2. MLAB as a high powered calculator. ===================================== You can have thousands of variables specified symbolic names in MLAB. For example, type: X1=8; X2=3; DX=X1-X2; These three statements assign numerical values to variables X1, X2, and DX. Note several MLAB commands can be typed on the same line if each command is separated by a semicolon (;). The name of a variable begins with a letter and may be followed by as many as 16 alphanumeric characters. If the MLAB system variable CASESW is set equal to 1, MLAB will distinguish between upper and lower case letters. The value of one or more variables may be printed by using the TYPE command. For example, type: TYPE X1,X2,DX results in: X1 = 8 X2 = 3 DX = 5 MLAB supports vector and matrix variables, too. To define a column vector named V containing ten zeroes, use the row-wise replication operator ^^ by typing: V = 0^^10 Different values such as 1.2, 1.9, 2.6, -3.2, 6.5, and 7, may be assigned to a column vector by using the LIST command as follows: VC = LIST(1.2,1.9,2.6,-3.2,6.5,7) To store an ordered sequence of numbers in a column vector, you may use the (start:end:step size) operator, for example: V1 = 2.4:9.6:1.2 stores the values (2.4,3.6,4.8,6,7.2,8.4,9.6) in column vector V1. Alternatively, you may use the (start:end!number of steps) operator, for example: V2 = 2.4:9.6!7 which stores the same numbers in column vector V2. A column vector may be converted to a row vector by using the apostrophe as a transpose operator, for example: VR2 = V2' defines VR2 as the transpose of V2. Matrices may be defined from vectors by using the SHAPE operator. SHAPE takes three arguments: the first argument is the number of rows in the result matrix, the second argument is the number of columns in the result matrix, and the third argument is the name of the vector of values which are read row wise. For example, type M = SHAPE(3,2,V2); TYPE M MLAB responds: M: a 3 by 2 matrix 1: 2.4 3.6 2: 4.8 6 3: 7.2 8.4 The values of a matrix may be read from an ASCII text file in the current working directory by using the READ command. For example, M = READ(DATVAL,4,3) will open the file "DATVAL.DAT" in the current working directory, read four rows of three floating point values from that file, and store them in the matrix M. Specific elements of a matrix may be assigned by using subscripts. For example, typing: M[3,1] = 6 changes the element of matrix M in the first column of the third row to the value 6. The elements of an entire row of a matrix may be assigned by using the ROW keyword; for example, M ROW 2 = LIST(7,9)' The keyword COL may be used in a similar fashion. Note that if a matrix must be enlarged to define an element, row, or column, then undefined elements are intialized to zero. For example, if MM has not been defined and one types: MM[3,4] = 6; TYPE MM MLAB responds with: MM: a 4 by 4 matrix 1: 0 0 0 0 2: 0 0 0 0 3: 0 0 0 6 The scalar arithmetic operations carry over to matrix operands: + and - performs element by element addition and subtraction, and * performs row by column matrix multiplication. The Moore-Penrose inverse of a matrix can be found by typing: M^(-1) The eigenvalues and eigenvectors of a square matrix can be found by typing: EIGEN(M) The selection of basic built-in functions offered by MLAB is far more extensive than what is offered by any calculator. These include: SIGN(X) - the sign of the value stored in variable X INT(X) - the integer part of the value stored in variable X MOD(X,Y) - the integer remainder after dividing the value stored in variable X by the value stored in variable Y ABS(X) - the absolute value of the value stored in X SQRT(X) - the square root of the value stored in X EXP(X) - the exponential of the value stored in X LOG(X) - the natural logarithm of the value stored in X SIN(X) - the trigonometric sine of the value stored in X (radians) COS(X) - the trigonometric cosine of the value stored in X (radians) TAN(X) - the trigonometric tangent of the value stored in X (radians) Trigonometric functions with arguments given in degrees are computed by adding a D to the function name (i.e. SIND(X) is the trigonometric sine of the value of variable X in degrees); hyperbolic trigonometric functions are computed by adding an H to the function name (i.e. TANH(X) is the hyperbolic tangent of the value of variable X in degrees). There are also many statistical distributions, density, and random number generator functions. For example, GAUSSF(X,Y,Z) - the value of the normal distribution function for random variable value X, mean value Y, and variance value Z STUTF(X,Y) - the value of the Student's T distribution function for random variable value X, and degrees of freedom value Y QFF(X,Y,Z,W) - the value of the F distribution function for random variable value X, numerator degrees of freedom value Y, denominator degrees of freedom value Z, and noncentrality value W (You need the MLAB Reference Manual to learn about the hundreds of basic and advanced mathematical and statistical functions found in MLAB.) You may define your own functions by using the FUNCTION statement (FUNCTION may be abbreviated FCT). Note the FUNCTION statement can only be used to define a function of one or more variables that returns a scalar; it is not possible to define a function that returns a vector or a matrix. For example, you can define a quadratic function of one variable, X, and three parameters, A,B, and C, and evaluate it by typing: FCT Q(X) = A*X^2+B*X+C A=3; B=2; C=-1 Q(3) The result is: = 32 You can evaluate a function at a number of independent variable values by using the ON operator. For example, type: Q ON 1:10 to evaluate the function Q(X) at X = 1,2,...,10. You can create a table of independent variable and function values by using the POINTS operator as follows: POINTS(Q,1:10) The POINTS operator takes a function name as its first argument and a vector of independent variable values as its second argument. It returns a two-column matrix, with independent variable values in the first column and the corresponding function value in the second column. MLAB can also compute derivatives of functions symbolically! Such derviatives are automatically computed and used in curve-fitting and in ODE-solving of stiff ODEs. Such derivatives can also be evaluated, and treated generally as the ordinary fuctions that they are. Simply type an apostrophe and the name of the independent variable following the function name to take the derivative of the function with respect to the independent variable. For example, to take the derivative of the previously defined quadratic function with respect to X, type: TYPE Q'X MLAB responds: FUNCTION Q'X(X) = 2*X*A+B You can evaluate the derivative at the point X = 3 by typing: Q'X(3) to which MLAB responds: = 20 [If you want to see an interesting feature of MLAB, try typing: FCT G(A,B) = ROOT(X,1,5,COS(X*B)^2-A*X); TYPE G(1,.5); TYPE G'A, G'B; TYPE G'A(1,.5)] 3. Curve-fitting with MLAB. =========================== Curve-fitting is one of the most important fuctionalities of MLAB. By curve-fitting in MLAB we mean estimating parameters that appear in a function of one or more independent variables so that the sum of, perhaps weighted, squared differences between the function value and some data is minimized and optionally specified constraints on the parameters are honored. Curve-fitting is achieved by using the FIT statement. The following statements demonstrate how to fit a cubic function to the four data points (-3,7), (5,4), (3,2), and (14.3,8), with the fourth data point given three times the weight of the first three data points. In what follows, comments that explain intent but are ignored by the MLAB command parser are delimited by /* and */: DT = SHAPE(4,2,LIST(-3,7,5,4,3,2,14.3,8)) /* define data matrix */ FCT F(X) = A*X^3+B*X^2+C*X+D /* define model function */ A=1; B=1; C=1; D=1; /* provide initial guesses for paramter values */ CONSTRAINTS E={A<2,B>0} /* define constraints on parameters */ WGTS = LIST(1,1,1,3) /* define optional weights for each data point */ FIT (A,B,C,D), F TO DT WITH WEIGHT WGTS CONSTRAINTS E To this series of commands, MLAB responds with: final parameter values value error dependency parameter -0.0161618283 4.465259163e-18 0.9996146809 A 0.309975808 6.9381617e-17 0.9996754586 B -0.687876879 8.657812469e-17 0.9599217076 C 1.7102177283 8.088386603e-16 0.949758177 D 7 iterations CONVERGED best weighted sum of squares = 1.972152e-31 weighted root mean square error = 4.440892e-16 weighted deviation fraction = 3.402982e-18 R squared = 1.000000e+00 no active constraints In this printout, MLAB gives the best parameter values, the standard deviation of parameter values (error), the dependency, the best weighted sum of squares and other statistics. For more information on the fit statistics, see the "MLAB Applications Manual". 4. MLAB as a graphical calculator. ================================== MLAB has an extensive repetoire commands for creating scientific graphs. To generate a graph of the data and the cubic function fit above, we use the DRAW and VIEW commands in MLAB. To draw the data points, give the command: DRAW DT LINETYPE NONE PT CIRCLE This specifies that the data points in DT should not be connected by any line segments (LINETYPE is NONE) but should be drawn with the circle POINTTYPE (abbreviated PT). To draw the fitted function, give the commands: FP = POINTS(F,-3:15) DRAW FP COLOR RED The first statement evaluates the function F at x-values = -3,-4,-5,...,15, and stores the x-values in column 1 and the corresponding function values in column 2 of the matrix FP. The subsequent DRAW statement draws line segments in the color red between each of the (x,y) coordinate pairs. Generally, the DRAW command takes a two or three column matrix as its first argument, followed by LINETYPE, POINTTYPE, COLOR, and LABEL clauses. A title can be given to the graph by typing: TOP TITLE "Cubic fit of data" FONT 7 MLAB also has: LEFT TITLE, RIGHT TITLE, and BOTTOM TITLE commands. MLAB offers 34 different character fonts; FONT 7 specifies the seventh one. To make the graph appear on the screen, give the command: VIEW This command will open another window at the upper left corner of the display screeb, and draw the default graphics window with the previously specified curves and titles, and default specified axes, axis labels, and colors. Consult the MLAB manuals and online help system for more complete discussion. To make the MLAB graphics window disappear from the display, give the command: UNVIEW You can also solve systems of ordinary differential equations with MLAB. 5. Solving ordinary differential equations with MLAB. =================================================== To clear previously defined scalar and matrix variables, functions, and graphics elements, type the command: RESET In order to solve an arbitrary ordinary differential equation of order m over a range of independent variable values, MLAB requires that you specify the m-th order derivative in a FUNCTION statement with lower order derivatives and functions of the independent variable on the right hand side; specify the initial values of the solution function and its first (m-1) order derivatives in m INITIAL statements, and specify the range of values of the independent variable in an INTEGRATE statement. For example, to solve Newton's equation of motion for a mass falling under the force of gravity from 10 meters above the ground and zero initial velocity, one can use the following statements: FCT Y''T(T) = -9.80 /* acceleration as the 2nd derivative */ INITIAL Y'T(0) = 0 /* zero initial velocity */ INITIAL Y(0) = 10 /* initial position */ YP = POINTS(Y,0:5:.05) The resulting matrix, YP, contains the time values 0,.05,.1,.15,...,5 in column 1 and the corresponding vertical positions of the mass in column 2. Note that MLAB automatically transforms the second order differential equation into two first order differential equations. You may also solve systems of differential equations by using the INTEGRATE statement in MLAB. As an example, we can solve Newton's equation of motion for a mass falling in two dimensions where there is only gravitational force acting on the mass in the y-direction, and an initial velocity in the x-direction of .1 meters per second, by adding the following statements to those above: FCT X''T(T) = 0 /* zero force in the x-direction */ INITIAL X'T(0) = .1 /* initial speed in the x-direction */ INITIAL X(0) = 0 /* initial x position */ XY = INTEGRATE(X,Y,0:5:.05) After the INTEGRATE statement completes, the matrix XY contains the functions and all derivatives at the times 0,.05,.1,...,5. To determine which column of the matrix XY corresponds to which function or derivative, type out the variable string ODESTR as follows: TYPE ODESTR MLAB will respond with: ODESTR = T X'T X'T'T X X'T Y'T Y'T'T Y Y'T One can then draw a trajectory of the mass with the following commands: DRAW XY COL (4,8) VIEW "VIEW" opens and gives focus to a second window called "MLAB Graphics" which contains the graph. This window can be moved or resized by using the mouse. Striking any key or clicking the mouse anywhere on the MLAB text window will shift focus back to the console window. To save a copy of the graphics image in the MLAB Graphics window, type PLOT MLAB responds PLOT file is mlabp0.ps This means MLAB has created a file named "mlabp0.ps" in the "MLAB" directory. The file contains PostScript instructions which define a full page rendition of the image that was in the graphics window. The ps-file may be opened with the Preview application provided with the OS X operating system and printed by double clicking on the Preview application icon and opening the MLAB ps-file by selecting OPEN from the Preview application's FILE menu. Then select PRINT from the FILE menu. Typing UNVIEW or clicking the close-box on the MLAB Graphics window causes the MLAB Graphics window to disappear. Next, try typing RESET This will free all MLAB memory used since the beginning of the MLAB session. DO-FILES ======== Lists of MLAB commands stored in a file--called a DO-file because the file name ends with ".DO"--can be executed by typing DO filename A text editor, such as EditText, vi, or emacs, is useful for creating and editing files which can be used as MLAB scripts. However such files should only contain ASCII characters; special characters such as those obtained by holding down the OPTION key and pressing another key will be ignored by MLAB. If such files are not saved in the "MLAB" directory, then the path to the directory where the file is located must be specified to MLAB prior to the DO-command with a FILEDIR command. To determine the working directory during an MLAB session, press the control key and strike the Z key to suspend the MLAB session, and type the command: pwd at the Unix prompt. Bash will then print the path to the current working directory. Typing fg after the next Unix prompt will resume the MLAB process. An example do-file called "DIMER.DO" is located in the MLAB directory. If you type DO "/usr/local/lib/mlab/DIMER" MLAB will execute the script and produce another graph. Note that the MLAB FIT command in the DIMER.DO file may take a few seconds to execute. Once the script is finished executing, you can review the history of the commands in the MLAB session by moving the elevator box in the MLAB terminal window with the mouse. You can copy and then edit the DIMER.DO file with the text editor of your choice. An on-line help system is available in MLAB. Type HELP at the MLAB prompt for a list of topics for which information is available, or type HELP topic-name for information about a specific topic (for example "HELP COS"). To conclude an MLAB session, type EXIT As MLAB terminates, it closes a file called "mlab.log" in the "MLAB" directory, which contains a record of the MLAB commands and responses in the MLAB session. mlab.log can be edited or printed using any standard editor or word processing program. -------------------------------------------------------------------------- MLAB USE OF FILES MLAB control files: MLAB.HLP gxfonts.0 TOKEN.FIL INIT.SAV DW.SAV gxserver Log-files: mlab.log, mlab0.log, ... Whenever MLAB is run, a record of the terminal dialog will be written in the file mlab.log. Moreover if mlab.log already exists it will be renamed to mlab0.log (and mlab0.log will be renamed to mlab1.log, and mlab1.log will be renamed to mlab2.log. Any existing mlab2.log will be deleted.) do-files: *.do DO-files are text files holding MLAB commands (i.e., script files for MLAB.) A do-file s.do can be executed by typing "do s". Startup do files: mlabinit.do $HOME/.mlabrc If the do-file .mlabrc is present in the user's home directory, it will be interpreted when MLAB is run. Also, if the do-file called mlabinit.do is present in the current directory it will be interpreted when MLAB is run. Save-files: *.sav MLAB can create binary files holding MLAB values (scalars, matrices, windows, functions, initials, strings) via the SAVE command. These files are called save-files and have the extension sav. The values stored in a save-file can be read into MLAB by means of the USE command. Plot-files: mlabp#.ps, mlabp#.lj MLAB can create PostScript and LaserJet plot-files by using the PLOT command. The file names for PostScript plot-files have an mlabp prefix followed by a number and a ps extension. The file names for LaserJet plot-files have an mlabp prefix followed by a number and an lj extension. Print-files: mlab.lst, *.lst, * MLAB can create print-files by using the PRINT command. Print-files have default name mlab.lst if no name is specified, and moreover subsequent print operations append to this file. A print-file has the default extension .lst if the file name with no extension is given. The full print-file name can also be given in quotes. Read-files: *.dat The READ operator in MLAB can be used to read numbers from a text-file. All files will be accessed in the directory specified by the MLAB control string FILEDIR, for example: if FILEDIR="/usr/george" then `PRINT mat' will create the file /usr/george/mat.lst In addition if the MLAB control string DOFILEDIR is set, then it will be used instead of FILEDIR to determine the directory where MLAB do-files will be sought. If FILEDIR (or DOFILEDIR) are null, the current directory is implied. end of readme.linux