Filename: ppcmac.readme Revision Date: September 24, 2015 Downloaded Trial MLAB Installation and Operation Guide This is the installation guide for the downloaded G3, G4, and G5 Macintosh OS X version of MLAB. This OS X version of MLAB is a native PowerPC OS X application that does not use OS9 compatibility software. MLAB also exists in DOS 640K overlay, DOS extended-memory flat model, 16-bit Windows 3.1, 32-bit Windows 95/98/NT/2000/XP, Intel-Linux, Motorola Macintosh OS 7/8, PowerPC Macintosh OS9, Intel Macintosh OSX,and several UNIX versions. This MLAB system has all the powers of full MLAB, but with a limited lifetime. 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 will 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. INSTALLING MLAB A downladable copy of MLAB for PPC Macintoshes running OSX is available at www.civilized.com. It is a "native" (not emulated) program. This file is called MLAB.zip and it is 1083311 bytes in size. It should take a minute or two to download (There are also versions of MLAB for Intel OSX Macs, and for earlier OS-9 PPC Macs, and for yet earlier OS-8,7 Motorola Macs.) Before you download MLAB for a PPC-Mac, you will want to look at the short Introduction to using MLAB found at www.civilized.com (You should print a copy for later reference.) The version of MLAB you will obtain is the complete program with an expiration date. After you pay for it and register it, it will then have an unlimited lifetime. On-line help about MLAB functions and commands is available (by typing "help" in MLAB), and there are three MLAB manuals that will be shipped to you by mail when you buy MLAB. You may also download the manuals in PDF format from www.civilized.com. When you click in your web-browser to download the OSX-native PPC-Macintosh MLAB program, a Macintosh archive file called MLAB.zip will be downloaded to your computer. Using the Safari browser, the default location of this file on your computer will probably be the directory /Users/[your user name]/Downloads/. (A directory is usually called a 'folder' in Macintosh parlance.) This is NOT an appropriate place. You should reset the download dirctory to be /Users/[your user name]/Desktop/; this is the "desktop". The downloaded file should then show on the "desktop" with a zip-file icon. Note, if you have your browser preferences set to automatically "open" downloaded files, then the downloaded MLAB.zip file is automatically "unpacked" and a directory called MLAB is created in the directory that was specified as the location to download into. This is also bad behavior. You should turn off the option to automatically "open" downloaded files. However, if you do "open" MLAB.zip in some inappropriate directory, you can manually move that entire directory to /Users/[your user name]/Desktop/. And, even if you do not automatically "open" MLAB.zip, you should manually move the file MLAB.zip to /Users/[your user name]/Desktop/ if necessary before you continue. When you have the file MLAB.zip in the /Users/[your user name]/Desktop directory (not already unpacked,) then you should double-click the MLAB.zip icon on your Desktop. This will run the BOMarchivehelper program to unpack the MLAB.zip file into a directory called MLAB in /Users/[your user name]/Desktop/. The reason it is helpful to have the MLAB directory in the Desktop directory is that Desktop/ contents are displayed with icons on your desktop screen, so that you can easily get to MLAB and run it. You can discard the MLAB.zip file after the MLAB directory is present. To run MLAB, double click on the MLAB directory icon on your desktop. The contents of this directory will be displayed. Now, double click on the MLAB executable file to run MLAB. (Later you may want to create an "alias" for MLAB on your "desktop". Before you run MLAB, it is important(!) that you print out this file intelmac.readme found in the MLAB directory on your desktop. The file intelmac.readme contains these directions plus other important information on using MLAB, such as how to 'navigate' the initial registration request, etc. When MLAB.zip is properly downloaded and unpacked, a directory icon (a picture of a "folder" labelled MLAB) will appear on your "Desktop". (The MLAB directory is now available to the user that owns the Desktop directory containing MLAB; it is not available to other users of your Mac OS X system unless you take appropriate steps to make MLAB globally accessible. To do this you need to know some basic Mac OS X and unix commands. In order to make MLAB available to all users, you need to run a terminal program and type the commands: su root (and enter the root password) chmod 711 /Users/[User name]/Desktop exit Basically, all the directories in the path /Users/[User name]/Desktop/MLAB need to be given execute permission for everybody. Usually the only directory that does not have such execute permission is the Desktop directory.) We will assume in the text below that the MLAB directory is in /Users/[User name]/Desktop. The files that have been established in the MLAB directory are: ppcmac.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 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 In the Examples sub-directory are 27 do-files for study and tutorial use: mlabex.do lrcex.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 fnpex.do magnetex.do mlabex1.do torex.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 LICENSING By installing MLAB, you agree to not use any parts of the MLAB files or manuals, modified or unmodified, as parts of any products without permission. You agree to register and use MLAB on one computer per license purchased. SYSTEM REQUIREMENTS To begin, verify that your G3, G4, or G5 Macintosh is hardware and software compatible with MLAB. 1) The CPU chip must be a PowerPC 601, 603, or 604 microprocessor. 2) The Macintosh must have a CD drive for the MLAB distribution CD. (However, MLAB can be downloaded from www.civilized.com and then registered as described below, if CDs cannot be read.) 3) To transfer the MLAB application to your computer will require a hard disk with at least 7.5 Mbytes of free disk space. 4) To run MLAB requires that the Macintosh have at least 3.0 Mbytes of free memory (RAM). 5) Macintosh Operating System version X is required. RUNNING MLAB Once MLAB has been installed by downloading and unpacking the files, you can start MLAB by running the Finder program, either explicitly, or implicitly by double-clicking on the MLAB "Folder" icon on the Desktop. Then you must display the contents of the MLAB directory, assumed to be in /Users/[User name]/Desktop. Then MLAB can be run by double-clicking on the MLAB application filename or file icon in the Finder window. Using the Finder, you can create an alias for the MLAB application and place this alias on the "Desktop" (i.e. in /Users/[User name]/Desktop) or in any other directory. (An alias is just an icon that specifies a small file that refers to an application program file. When the alias icon is double-clicked, this causes the OS X Finder program to run that program.) The MLAB alias is created in the /Users/[User name]/Desktop/MLAB/ directory by displaying that directory with the Finder and clicking on the mlab file and then clicking on the Make Alias option in the Finder's FILE menu. When you have an MLAB alias icon on the Desktop, you can directly execute the MLAB application by double clicking on it. It is convenient to change the title text in the alias icon to "MLAB application alias", or some such descriptive text. (You can do this by holding the mouse button down on the title text in the alias for a second or two, following which you can type in the new title text.) After double clicking on the MLAB application icon or its alias, MLAB will start to run. First a moveable, scrollable, and resizeable window titled "Terminal - mlab" will be put in the center of the screen. (This is a "Darwin" terminal.) All subsequent MLAB dialog will appear in this terminal window. MLAB prints the date, time, version information, MLAB path, and the owner's name in the terminal window, and displays a small menu from which you either execute examples or go to top-level MLAB where you can execute MLAB commands and/or DO-files. (DO-files and data-files must be in your "working" directory unless you set FILEDIR or DOFILEDIR appropriately.) It is recommended that you run examples the first times that you try MLAB. Finally, you can also run MLAB by starting a Darwin window (you should arrange to get the Darwin terminal program to run as a startup program, if you are going to use Unix commands to run MLAB. This is how we do it.) In the Darwin window, you can run MLAB by typing the filename for the MLAB executable. This filename must, of course, be appropriately prefixed by any needed path information. It is convenient if you change your PATH environment variable to include the path to mlab. The mlab executable will normally be /Users/[User name]/Desktop/MLAB/mlab. [Running MLAB from a Darwin window is the preferred way to run MLAB because you can first do a cd command to establish the working directory that you desire.] When MLAB is running in a Darwin Terminal window, you can customize various aspects of the Darwin Terminal window, such as the font, font color, font size, and the number of lines of history to be stored in the command buffer, by clicking on the Terminal menu and selecting Preferences from the drop-down menu. A given set of such preferences can be saved for subsequent MLAB sessions. 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 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 trial 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 do so when you are satisfied that MLAB is useful to you. [The price is $1495].) 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.) As you continue to use MLAB, you will be asked each time 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 and can not be run after this, unless it is re-registered there. 3. Install MLAB from the CD, or via downloading the trial version, 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 FIRST 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 DO-file script startup.do found in /Users/[User name]/Desktop/MLAB. The DO-file startup.do posts a menu with 3 choices in the MLAB 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. If you select the first option to view some examples by striking the ENTER key or clicking CONTINUE, a brief dialog of instructions is displayed. Click on the CONTINUE button and another menu with a list of example topics will appear. You can then choose a topic with the mouse or the UP and DOWN arrow keys and execute the corresponding DO-file by striking the ENTER key or clicking CONTINUE. Another choice is to go to the top-level MLAB prompt to do your work, but, when you first start using MLAB, you should study a few examples before you do that. When you opt to "go to" top-level MLAB, MLAB prints an asterisk (*) in the MLAB terminal window. The asterisk is the command prompt -- that is your cue to type MLAB commands. EXITING MLAB You should exit the MLAB program by typing the command EXIT to MLAB. However, there are several other ways the MLAB program can be quit. These are 1) click on the close control button of the Darwin window. 2) click on "Terminal" and select "Quit Terminal" from the drop-down menu. 3) press the Apple and Option keys and strike the ESC key (i.e. type Apple-Option-Esc) and quit MLAB from the dialog window that appears. 4) type ^C to MLAB and select the choices that allow you to quit MLAB. When you have run MLAB by typing the executable file name in a Darwin terminal, then using the exit, ^C, and the Apple-Option-Esc methods of exiting will result in a prompt in your Darwin terminal from which you can continue issuing Unix commands. If you use the close control button or the "Quit Terminal" option to exit MLAB, then the Darwin window will be destroyed, as you requested. When you have run MLAB by double clicking on the MLAB ALIAS icon, then using the exit, ^C, and the Apple-Option-Esc methods of exiting will result in [process terminated] appearing in your Darwin terminal and you may not enter any further commands! The only thing you can do is destroy that Darwin terminal window. 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; often this might be just the directory /Users/[User name/Desktop/MLAB where the MLAB executable is stored. A file can be edited using the TextEdit editor application by typing the MLAB command: EDIT FILE after the MLAB command prompt, where is the name of the file to be edited. If the file does not exist, MLAB will generate a prompt asking if the file should be created. If you select the create file option by pressing the C key, then MLAB will create the file and open a TextEdit window for editing the named file. (Note, the TextEdit window may or may not be obscured by the MLAB Darwin terminal window, and it may be necessary to click on the title bar of the TextEdit window to give it keyboard focus and make it the foremost window.) After editing and saving the file with TextEdit, terminate the TextEdit application and MLAB will resume. [Using TextEdit requires certain preliminary actions and understanding of its idiosyncratic nature. Before you run MLAB, you must reconfigure the TextEdit program to read and save plain ASCII text files, rather than .rtf or .html files. You do this by running the TextEdit program and then clicking on "TextEdit" and then clicking on "Preferences" to bring up a control window that will allow you to specify reading and writing plain text files. In this control window, change the "Format" to "Plain Text". Then click on "Open and Save" at the top to obtain the second control window. In this window, check the box for "Save files as Read & Write" and uncheck the box for "Add .txt extension to plain text files". Now in MLAB, you can use the TextEdit program by typing the command EDIT FILE . For example, you can type "edit file toy.do". MLAB will ask if you want to create that file, and you will type "C" to permit the file to be created. TextEdit will then display its text input window using the filename you specified. (The TextEdit window may pop-up behind other windows; in that case, you must manually bring it to the front.) You should then enter the text that defines your do-file. You save this text by clicking on "File" and selecting "Save". An unnecessary warning message complaining about "nil or empty path argument" will appear in the Darwin terminal window. Nevertheless, TextEdit has saved the file toy.do in your working directory. Then you must click on "TextEdit" and select "Quit" in the menu that appears. If you do not quit in this manner, TextEdit will not relinquish control to MLAB. Now you can type the command "do toy" in MLAB to execute the do-file toy.do. You can change the file toy.do by typing "EDIT FILE toy" in MLAB to run the TextEdit program again. This time the content of the file toy.do will appear in the TextEdit input window.] If for the first invocation of TEXT EDIT during an MLAB session no filename is specified, MLAB opens the default do-file: TEMP.DO. If for the second or later invocation of TEXT EDIT no filename is specified, TEXT EDIT will open the last named file among previous TEXT EDIT commands. Finally, if the command: EDIT FILE "" is given, the TextEdit application is started without opening a file. Some people find it easier to run a second Darwin terminal window and run either vi or emacs there, to edit do-files. (This is the way we run MLAB.) Of course, you must be sure you save the do-files in the appropriate directory, and that you have FILEDIR and DOFILEDIR set appropriately. This is considerably easier and quicker than using TextEdit, since you do not have to quit emacs each time you go back to MLAB, all you need to do is edit the file that is showing and save it with the coommand Ctrl-x Ctrl-s. HOW TO SPECIFY DIRECTORIES When you run MLAB, you have a "working directory" established. By default this working directory is /Users/[User name]/. If you explicitly open a Darwin terminal window, you can use a cd command to select a working directory of your choice, and then run MLAB by typing: /Users/[User name]/Desktop/MLAB/mlab, then your working directory is whatever you have chosen by explicitly cd'ing. If you run mlab by clicking on the mlab alias icon then your working directory is /Users/[User name]/. If you run mlab by double clicking on the MLAB filename in a Finder window, then your working directory is /Users/[User name]/. If you want some other directory to be your working directory after you run MLAB, then 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. When the EDIT FILE command is used, the specified file will be searched for and, later stored in your working directory, modified by or superceded by the directory path information specified in the MLAB string variable "FILEDIR". (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 Unix bash shell running in the Darwin terminal 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. It is probably more convenient to open another Darwin Terminal window and run emacs or vi there, as discussed above.) 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. If you wish your MLAB working directory to be /Users/[User name]/Desktop/MLAB, you may reset FILEDIR with the MLAB command: FILEDIR = MLABPATH (the MLAB string variable, MLABPATH, is initialized to the string "/Users/[User name]/Desktop/MLAB"). Since your usual default working directory is /Users/[User name], you can get the same effect by setting FILEDIR to "Desktop/MLAB". In this case, 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. Also note that after MLAB has printed the user prompt, you may change many of the settings for the Darwin Terminal window, including width and height of the window, type of font and fontsize, foreground and background color of the text, etc. These settings are controlled from the Window Settings options on the menu that drops down from the Terminal title located at the top menu bar on the screen. ------------------------------------------------------------------------- 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 /Users/[User name]/Desktop/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: - 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 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. MLAB data in ASCII text 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 /User/[User name]/Desktop/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 LJ2L, 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. If you run MLAB by clicking on the mlab icon in the MLAB folder on the Desktop without setting FILEDIR or DOFILEDIR directory strings, then MLAB log files will be created in the directory /Users/[Username]/, as will all PRINT, SAVE, RESAVE, and PLOT output files and all REUSE, USE, DO, and REUSE input files. If you run MLAB by opening a Darwin terminal window, changing to a directory and typing /User/[username]/Desktop/mlab/mlab then the MLAB log files will be created in the directory where the MLAB command was given, as will all PRINT, SAVE, RESAVE, and PLOT output files and READ, USE, DO, and REUSE input files. 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. The up/down arrow keys can be used to scroll through the history of typed MLAB commands and display them. When the command you wish to re-execute or edit appears, you may edit it, and then re-execute it by hitting the Return key. [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. The Mac OS X operating system has an exception reporting program called CrashReporterd that is automatically run when you boot your computer. This program watches for exception signals and when one is detected, it posts a "error report window" on the screen (and writes appropriate information in a error log file). The CrashReporterd program has no knowledge that MLAB handles its own arithmetic exceptions. As a result, you may be confused by such error reporting windows popping up on your display screen. All you need to do is to click on any of the options listed to make that error report window disappear. MLAB is still running and is completely unaffected by this action. Only one error report window will ever be seen for a given MLAB session. You can get rid of this annoying behavior of the CrashReporterd program in one of several ways. You can "kill" this program before you run MLAB. You do this by running "ps -ax" in a Darwin Terminal window, noting the process number of the running CrashReporterd program, becoming root via the command "su root", killing the CrashReporterd program with the command "kill ", and typing "exit" to exit being root. Alternately, you can run the CrashReporterPrefs application and turn off CrashReporterd pop-up window reporting. This only affects the logged-in user. Turning off CrashReporterd pop-up windows does not keep CrashReporterd from running and from writing in its error log-file; as a result, this method is less efficient than simply killing CrashReporterd. You can turn off CrashReporterd pop-up window reporting by running the application CrashReporterPrefs. CrashReporterPrefs presents a dialog window. You should select "Server" by clicking on the adjacent button; then click on the close-window button at the upper left to exit CrashReporterPrefs. To run CrashReporterPrefs, open a Finder window (i.e. run the Finder program), and then click on the FILE control to display the FILE-menu for the Finder application. Then select FIND from the FILE-menu, type in "CrashReporterPrefs" and double click on the CrashReporterPrefs filename that appears, to run the CrashReporterPrefs program. (If you know how, you might want to change the OS X startup scripts to prevent CrashReporterd from ever running. This would work for all users all the time.) 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 screen, 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 The OSX window controls on the MLAB picture can be used with more or less utility. If you click on the green "zoom" button, the picture is enlarged to fill most of the screen. If you click on the green "zoom" button again, the picture is restored to its original size; thus the "zoom" button is a toggle control. If you click on the yellow "iconize" button, the picture is replaced by an icon-sized copy of the picture in the "dock". You can run other programs while the MLAB picture is iconized, but you can do nothing useful with MLAB until you click on the icon picture to restore the original MLAB picture. If you click on the red "delete" button, the picture is removed from the screen; this is equivalent to an UNVIEW command. You can restore the picture by typing the command, VIEW, to MLAB. 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 create a printable PostScript file containing 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. The Macintosh screen-capture key combination (Command-Shift-3) and the window-capture key combination (Command-Shift-4) can be used to generate PDF file images of the screen and MLAB graphics window while the MLAB application is running. Such PDF files are stored on the disk in the directory /Users/[User name]/Desktop with names such as "Picture 1.pdf", "Picture 2.pdf", etc. 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. The OS X operating system 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 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 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, either type EXIT or select QUIT from the FILE menu. 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 most standard Macintosh editors or word processing programs. end of ppcmac.readme