file: mlabfiles.txt date: October 1, 2009 This is information for running MLAB under an MSWindows operating system. You may want to print this text and keep it for reference. Some details differ for Mac OSX and for Linux, but this information is still valuable for those systems. A Quick Example of using MLAB: ------------------------------ When you run MLAB, a "console" window is put on the screen, and a smaller "start-up menu" window is displayed in which you must make a selection. Actually, the very first time you run MLAB, you will be asked for a "user-name", that is kept just for display purposes, before the start-up menu is presented. And later on, until you "register" MLAB, you will be asked for an "authorization key-value" that you obtain from Civilized Software. When you obtain the authorization key-value and enter it, you will never be asked for it again. Until you obtain your authorization key-value, you should enter "0". After responding, the start-up menu window will be displayed. One choice in the start-up menu window is to run various examples. Another choice is to go to "top-level", which means that the menu window is removed from the screen, and a "*" prompt symbol is displayed in the console window; this prompt means that MLAB is 'waiting' for you to enter an MLAB command. There are dozens of MLAB commands and hundreds of MLAB functions waiting to be used. In essence, MLAB is an interpreter for a high-level mathematical language and you use MLAB by specifying purposeful sequences of MLAB commands to accomplish your end. (As a practical matter, you will probably often enter these commands in a text-file to construct a re-runnable 'script' called a do-file.) You can define a function and graph it as follows. function f(x) = a*cos(b*x)*exp(-k*x) a = 1; b=4; k =.5 v=1:10!100 m= points(f,v) draw m view Note 1:10!100 = 1:10:.0909090909, and 1:10:.0909090909 means the column vector of values from 1 to 10 in steps of size .0909090909 (So can you guess what 1:10!100 means in 'plain English'?) Also note points(f,v) = v&'(f on v), and v$'(f on v) means the column-wise concatenation of the matrix v with the same-sized column vector consisting of the values of f computed on the values in v. (What do you think the operator & does as opposed to &' ?) By the way, ncols(f on v) is the same as ncols(v), but the &' operator does not require this; what do you think v$'7 is? You can read-in 110 data values from a file into a 2-column matrix as follows. The result is a 55 row by 2 column matrix. d = read("filename",55,2) Taking the rows of d as (x,y) data-points - with error in the y-values - as data points "modeled" by the function f, defined above, you can estimate the unknown parameters a,b,k as follows. fit(a,b,k), f to d You can use estimated weights for the various data points in d based on a moving variance estimation function ewt as follows. fit(a,b,k). f to d with wt ewt(d) You can graph the data and the "fit" as follows. delete w /* to discard any previous picture */ draw d linetype none, pointtype circle draw points(f,d col 1) color green view You can look at the symbolic derivative of f and graph it as follows. type f'x draw points(f'x. d col 1) color red view Note MLAB can use symbolic-dervatives when derivative values are needed during curve-fitting. Also note you can fit (or just solve) differential-equation-defined models in MLAB, so that chemical kinetics and physiological and compartmental models, etc. can be handled. Try this: a=3.14159e200 b= -(10e201) type a,b, a*b Now try that with any other computational program you have access to. (This behavior is often useful in curve-fitting. Can you see why?) Note, you can probably see that you need to have the MLAB manuals available because there is so much in MLAB that you will miss otherwise. You can find a link "upstairs" at www.civilized.com that offers the option to download the MLAB manuals in PDF format. -------- The MLAB Executable Directory and the MLAB Working Directory: There are two important directories (or "folders") that you must(!) be aware of when running MLAB. The first is the "MLAB executable directory", and the second is your "current working directory". The "MLAB executable directory" is that directory where the MLAB executable program file (and other MLAB system files) are stored. This directory is established by the MLAB setup program which is run when MLAB is installed. Generally, this directory is C:\MLAB\ unless some other directory was specified to the setup program. In any event, you MUST know the full path and the name of this directory. You should write it on a piece of paper and tape it to your computer. (MLAB prints-out this full directory name when it is run.) Your "current working directory" is that directory where you want to get your "input" and write your log-file and other output, at least for "today". When you run MLAB and ask it to execute a do-file (an MLAB script,) or read a data-file, then, unless you specify a specific path as part of the file-name (or set the FILEDIR variable,) the current working directory will be the place that MLAB looks for such files. Thus the directory where you keep do-files and data-files for some project is the directory that you want to make your current working directory when you want to deal with that project. -------- In a Unix/Linux system, MLAB is run by starting a "terminal-emulator" program (like xterm) and then 'cd'-ing to the directory that you want to be your working directory, and then running MLAB by typing "MLAB" at the 'command-line'. ('cd' stands for 'change directory'.) You can run MLAB the same way in a Windows system (almost). You start a so-called DOS window (labeled a "command-prompt" window in XP,) and set the 'volume' (e.g. D:) and 'cd' to your desired working directory, and then run MLAB by typing "MLAB" as the next command. In this case, the working directory is established as you want it. Note, however, unlike in Unix, MLAB puts its own "console" window on the screen wherein all MLAB commands are entered and printed, and where text-output occurs. Thus the DOS window is only used to get MLAB started with the desired current working directory. Also, note that to run MLAB from the "command-line" in either Unix or Windows, you must have the MLAB executable directory in your PATH environment variable, or else you must specify the fully-qualified name in order to run MLAB (e.g. C:\MLAB\MLAB). Without any 'cd' command, when you run MLAB from within a DOS-window, your current working directory will start-out being the directory specifed as the "start-in" directory associated with the DOS or CMD icon. By default, in XP, this "start-in" directory is C:\windows\system32\. (It is thus generally a bad idea to run MLAB in a DOS windows without explicitly cd-ing to where you want to be.) [You may need to establish a "desktop shortcut icon" for the cmd.exe program generally found in C:\windows\system32\ in order to conveniently run the 'DOS interpreter'.] There are two other ways to run MLAB in Windows. One way is to run the MS file-finder program (by clicking start -> find, or start -> search) and "navigate" by clicking to the MLAB executable directory, and then double-click on the MLAB executable file, mlab.exe, to run it. In this case, your initial working directory will be the same as the MLAB executable directory, and you will need to use FILEDIR to "override" this. The final way to run MLAB is to double-click on an MLAB "short-cut" icon on the "desktop". (Such an icon will be created upon request when the MLAB setup program is run at the time MLAB is installed - and if you know how, you can create a short-cut icon yourself at at any time.) When you run MLAB in this manner, your initial working directory will be whatever is set as the "start-in" directory associated with the 'icon' (Clicking on the icon actually causes Windows to refer to a collection of files that tell it the full-name of the associated executable file, and various other properties, including the "start-in" directory.) Generally the "start-in" directory associated with the MLAB short-cut icon is the MLAB executable directory, but you can change this by right-clicking on the MLAB short-cut icon, and clicking on the "shortcut" tab in the window that pops up, and then changing the "start-in" text-field to whatever you want it to be. Thus, before you run MLAB, you could do this to set the "start-in" directory, And you might re-do this whenever your desired working directory is different from whatever is set. ---------- In all cases, MLAB will write a session log-file in the initial working directory! This log-file will be called "MLAB.LOG" (and the earlier log-files found there will be renamed with the 'shifted' names MLAB1.LOG, MLAB2.LOG, etc.) The session log-file is convenient. You can print it to obtain a record of what you did. You can extract text from it to construct a do-file. And you can review error messages recorded there to "debug" an MLAB do-file. (You will need to use some simple ASCII text editor such as Notepad to do these things.) Even if you start MLAB with the MLAB executable directory as the initial working directory, you can, in effect, change directories at will as you use MLAB. There is a control variable in MLAB called FILEDIR. This variable is a string of text that is prepended to every file-name you refer to in your MLAB session! [Your session log-file, MLAB.LOG, will, however, be created in the initial working directory that is set or that MLAB is given by Windows. Setting FILEDIR has no effect on where the log-file is.] The FILEDIR variable starts-out as the empty-string. Thus, assuming FILEDIR is empty, if you type 'DO afile' in MLAB, you are referring to the file afile.DO in your current working directory. If, however, you set FILEDIR - for example: FILEDIR = "C:\project1" (or FILEDIR = "C:\project1\") and then type 'DO afile', you will be asking MLAB to execute the do-file 'C:\project1\afile.DO'. (Note you need to know the DOS/Windows notation for specifying a "path", i.e a fully-qualified directory on a specified disk-partition 'volume'.) The same prepending of FILEDIR occurs for all files you refer to in MLAB. Thus, for example, if you read a data-file into a matrix with the command 'm = read(dfile,120,2)', you are actually asking MLAB to read the first 240 numbers found in the ascii-text file dfile.dat within the directory specified by FILEDIR into the 120-row, 2-column matrix m. There is an exception to the FILEDIR prepending rule in MLAB for do-files. If the MLAB control variable DOFILEDIR is set to a non-empty string, then this string, rather than FILEDIR is prepended to any do-file name that is specified to MLAB. (This lets you access do-files in a particular directory (specified by DOFILEDIR), while accessing other files in some other directory (specified by FILEDIR.) Thus, if you have your "project" data-files and do-files stored in some specially-named directory (and it is generally a good idea to work in this way,) then the first command you should execute in MLAB is: "FILEDIR = "xxx", where xxx is the fully-qualified path to the desired working directory. (Remember, you can change your working directory at any time in an MLAB session by resetting the FILEDIR string control variable appropriately.) When you run MLAB, a "console" window is put on the screen, and a smaller "menu" window is displayed in which you must make a selection. One choice is to run various examples. (The first few times you run MLAB, you should look at some examples!) Another choice is to go to "top-level", which means that the menu window is removed from the screen, and a "*" prompt symbol is displayed in the console window; this prompt is waiting for you to enter an MLAB command. Once you are at "top-level" and able to enter MLAB commands, you can use the up-arrow and down-arrow keys to "scroll" back through the previous MLAB commands and responses. Hitting the Enter key will take you back to the 'current' prompt line. (You will note there are no scroll bars on the MLAB console window; the arrow keys are the way you "scroll" in the MLAB console window.) In addition to looking at the previous lines in the console window, you can "select" a line by hitting the Insert key. This will cause the selected line to appear at the 'end' of the console window as the subject of a simple single-line editor facility in MLAB. You can then modify the selected line, and hit the Enter key to execute it. (When you enter an MLAB statement which is malformed in some way, you will receive an error message and the malformed line will be re-displayed in the MLAB single-line editor facility where you can (attempt to) repair the error and re-execute the line. You can also abort this 'editing' and just go to a new '*'-prompt.) ================================================= MLAB reads, writes or otherwise uses the following files or types of files. -------- 1 - gxfonts.0: a binary file containing the 34 MLAB stroke font definitions. gxfonts.0 is a read-only file and found in the directory where the MLAB program file is located. The file is accessed whenever a title string or axis label is to be drawn in the MLAB graphics window. -------- 2 - mlab.hlp and mlabref.hlp: files containing text used by the MLAB HELP systems. These read-only files are found in the directory where the MLAB program file is located. mlab.hlp is read when either the commands "HELP" or "HELP topic" are given by the user. The file mlabref.hlp is read when the user strikes the F1-key to access the special Windows help presentation system. (This text is not very useful.) Also the content of the MLAB help-file, mlab.hlp, that is accessed via the "HELP" command, although useful, is incomplete, and sometimes wrong, so be sure to depend on the MLAB Reference Manual as the final authority. -------- 3 - mlab.log, mlab0.log, mlab1.log, and mlab2.log: These are ASCII text files containing the dialog of the current MLAB session (in mlab.log) and the previous three MLAB sessions (in the files mlab0.log, mlab1.log, and mlab2.log). These files are created by MLAB in the user's working directory and are useful for seeing a record of MLAB results. They are also useful for constructing .do-files, since you can copy the text in an mlab log-file and edit it to construct a do-file. It is also useful to look at an mlab log-file to aid in debugging an mlab do-file. (Note: see the definition of the system variable ECHODO, below.) -------- 4 - .do-files: An mlab do-file is an ASCII text file containing comments and MLAB commands, i.e. a 'script' in the mlab language. Such a 'script' can be repeatedly re-run, and also easily changed as desired. Constructing and running a do-file is the preferred way of using mlab whenever you have a relatively substantial computation to do. An example of a .do-file is the file DIMER.DO in the directory containing the MLAB program file. Also there are example .do-files in the MLAB\EXAMPLES\ directory. A do-file can be generated with any ASCII text editor, such as the MSWindows Notepad Accessory program. DO NOT USE MS-WORD to create or change do-files or data-files intended for use in MLAB unless you know how to save files as ordinary text files! MS-WORD generally 'saves' binary files. (and remember "rich" text is NOT text!)- use Notepad or some other editor that can save plain ASCII .txt files easily.) The MLAB command: [EDIT FILE filename.do] will run the Notepad program for editing the specified new or existing .do-file from within an mlab session.. When running the Notepad editor via the EDIT FILE command within mlab, the named .do-file is searched-for or created in the directory specified by the path in the DOFILEDIR control string. If DOFILEDIR is null, then the directory specified by the path in the FILEDIR control string is used. If FILEDIR is null, then the initial "start-in" working directory is used. MLAB .do-files contain MLAB commands and comments. Comments begin with the 2-character sequence: /* and are terminated with the 2-character sequence: */. Comments may span multiple lines. Note, comments may NOT be embedded within enclosing comments. If more than one MLAB command appears on a line of a .do-file, they must be separated by semicolons (;). (There are other situations where terminating semicolons must be used as well.) An MLAB .do-file is executed by the command: [DO filename.do]; that's why it is called a do-file. The three scalar control variables DOSTEP, ECHODO, and CASESW control aspects of general mlab execution and .do-file execution. If DOSTEP = k (a positive integer), then MLAB will pause--waiting for a key to be struck by the user--after every k lines in the .do-file have been executed. Thus, DOSTEP=1 will allow you to "single-step" through the do-file, perhaps, looking for a line that cause an error messsage. If DOSTEP = 0, which is the default case, then a DO-command will run the specified do-file without interruption to completion, unless MLAB commands requiring keyboard input are encountered, or there is an error detected. The control scalar ECHODO controls the "echoing" of do-file commands to the screen and the log-file, mlab.log. If ECHODO = 0, then the .do-file is executed silently--no commands are echoed to the screen or the log-file; if ECHODO = 1, then the lines of the .do-file are echoed to the screen but not the log-file; if ECHODO = 2, then the .do-file is echoed to the log-file but not the screen; and if ECHODO = 3, the do-file is echoed to both the screen and the log-file. The control scalar CASESW controls the case-sensitivity of MLAB names. If CASESW = 0, then upper-case characters are not distinguished from lower-case characters; all input is converted to upper-case, except within quoted-strings. If CASESW = 1, no such conversion is done, except for control variable names, mlab function names, and mlab reserved syntax words, like "TYPE" or "DO". The implications of using CASESW =1 are sometimes subtle, especially with identifiers used as filenames, and we reccomend you keep CASESW set to 0. (MLAB generaly tries both upper-case and lower-case versions of filenames in an attempt to not disappoint the user.) . -------- [How to Use MLAB] The most convenient way to run MLAB when you have a repetitive or a complex computation to do, is to setup a do-file to do it. (Remeber you can do this by typing EDIT FILE xdofile.do to create the do-file xdofile.do in your working directory.) You should be sure to put comments in your do-file to define all the variables and functions, etc. and don't forget to include comments specifying the units for all data where this is important. Note, it is convenient to give the commands "reset; echodo=3" as the first commands in your do-file. Also, remember the READ, READON, KREAD, and SREAD MLAB functions. Another tip is that you can construct strings by concatenation and you can execute such a string containing a sequence of MLAB commands as a do-file! For example, try z=99; S="type "+"value of z:"+z; do S; and you can construct more elaborate and useful examples. [You should look at the file startup.do and the do-files provided in the examples sub-directory.] After your do-file is written and saved on disk, you should print it (You can use the MLAB command "PRINT FILE xdofile.do" to get this listing.) Then you should read your do-file, add more comments, and verify that it does what you want to the best of your ability. (Remember to keep the MLAB manuals close at hand.) After you have iterated this step as much as you feel is helpful, you should then run MLAB and use the command "DO xdofile" to run your do-file. (Remember you will need to have set-up any data-files or other do-files that your do-file reads. It is quite likely that there will be errors in your do-file. If you can see what the problem is, you can just tyoe "EDIT FILE xdofile.do" and fix your do-file and resave it on disk. [You should leave the NotePad editor window 'open', so you can use it again in a few moments.] Then you can just type "DO xdofile" again, and see what happens. You can "flip" back and forth between NotePad and MLAB, until your do-file is "debugged". Sometimes it will be helpful to put TYPE statements in your do-file so it will tell you the progress of execution. This is just one of the standard debugging devices that can sometimes be helpful. When your do-file is debugged, it can be run whenever you wish by running MLAB and typing "DO xdofile". Of course, for all your work with MLAB, you must be aware of your current working directory and have FILEDIR set appropriately. One useful 'trick' you can use in a do-file is the command [DO KLINE], 'KLINE' stands for "keyboard-line". When this command is executed, MLAB will type a '>' prompt and wait for input. Whatever is typed will be executed as a do-file. Note this is a good way to pause if you don't want to use the undocumented MLAB PAUSE statement. Also, you can use DO KLINE in other ways like: [type "enter the desired function as 'fct f(x)=...':"; do kline;] (Here are some other experiments you should run. [do dofilename], [do "dofilename"], [do ksread()], [do ""+ksread()].) MLAB Example Do-Files All the examples that are available to you from the start-up menu are just .do-files that that are stored in the sub-directory 'EXAMPLES' in the MLAB executable directory (generally C:\MLAB\). You should go look at those .do-files (using Notepad, or using the 'type' command or 'edit' command in a DOS-window.) One of the interesting things you will see in some of the example .do-files is how to use the 'MENUCHOICE' and 'GETSTRINGS' MLAB functions that allow you to make your own menus and to obtain text input. (See in particular the Hogkin-Huxley Nerve Axon Model example.) There are many other interesting "lessons" to be found in the example .do-files as well. You can copy any of these do-files into your working directory, and then modify it to construct your own do-file. This is particularly appropriate if you want to do a computation related to one of the example do-files. -------- 5 - .dat-files: .dat files are plain ASCII files containing numbers to be read-in as data; the READ command is used to do this. Examples of .dat-files appear in the MLAB\EXAMPLES\ directory. (The READ command scans the specified file for numbers given by ASCII characters in any "standard" form, such as 123 or 12.34 or -3.1e12, etc. All other bytes are ignored; thus the mlab READ command can read appropriate non-ASCII files too.) As with .do-files, .dat-files can be created or modified with any ASCII text editor, such as the MSWindows Notepad Accessory program. And, as with do-files, The MLAB command: EDIT FILE can be used to construct or change a dat-file. Note, the MLAB string variable DOFILEDIR only affects the path for .do-files, and does not affect the location of .dat-files so that .do-files and .dat-files can be read from different directories. A .dat-file can also be created using Notepad, or any other program as long as it contains the numbers you want (and only those numbers) in ASCII (i.e. .txt format.) DO NOT TRY TO READ MS-WORD or EXCEL FILES IN MLAB UNLESS YOU KNOW THEY ARE TEXT FILES. Files created by MS-WORD and by EXCEL are generally not text files unless you know how to save them, they are usually binary files. (and remember "rich text" is NOT text!)- use Notepad or some other editor that can save plain ASCII .txt files easily.) The numbers in a .dat-file are read and stored as the elements of a matrix M by using the READ command: M = READ("filename.dat",nr) This READ-command will read nr or fewer values from the file filename.dat in the implicit directory (either specified by FILEDIR or established at initial start-up.) The i-th successively-read value is assigned to M[i] (so M will be a one-column matrix.). The input file will be scanned for numbers embedded in ANY non-digit text. However, you can prevent any text you want from being scanned by enclosing it in "'s or by the C-comment brackets /*, */. When FILEDIR is null, the read command [M = READ("C:\DX\DY\S.DAT", rr)] reads rr numbers from the file C:\DX\DY\S.DAT into M as a single column of rr values. (If the file does not contain rr numbers, then all the numbers present will be read.) Data matrices with nr rows and nc cols can be constructed with the following command: M = READ("filename.dat",nr,nc) If a .dat-file contains values for more than one matrix, a special version of the READ command can be used. the READON command can be used sequentially, as: M1 = READON("filename.dat",nr1,nc1) M2 = READON("filename.dat",nr2,nc2) . . . MN = READON("filename.dat",nrn,ncn) Each READON command continues reading in the input file where the previous READON command left-off. There are other MLAB data-input commands you should learn about - notably the KREAD and KSREAD functions. -------- 6 - .ps or .lj-files: A .ps file is an ASCII file in the Adobe PostScript graphics language. A .lj file is a binary file containing or Hewlett- Packard PCL language. Both forms of output files are called "plot-files". They contain the printer commands for an MLAB graphics picture. After creating an MLAB 'picture' (consisting of one or more MLAB "windows" all within the main mlab graphics window, using the DRAW command, etc.), the MLAB-command [PLOT] will generate a plot-file in the current working directory. This plot-file is either a file named MLABP#.PS containing commands suitable for printing on either a PostScript-capable printer or a printer on a computer with appropriate conversion software like Ghostscript, or it is a file named MLABP#.LJ containing HP PCL-GL/2 commands suitable for printing on a GL/2-compatible printer. the symbol # denotes the next succesive integer in the sequence 0,1,2,... (e.g. the first PLOT command writes-out MLAB0.PS, the next PLOT command writes-out MLAB1.PS, etc.) If the MLAB control variable PLOTDEV is set to PSL (or "PSL" - try typing PSL) then a .PS plot-file is created containing a black and white, Landscape orientation Postscript picture.) If the MLAB control variable PLOTDEV is set to PSCL (or "PSCL"????) then a .PS plot-file is created containing a color, Landscape orientation Postscript picture.) If the MLAB control variable PLOTDEV is set to HPLJ (or "HPLJ") then a .PS plot-file is created containing a black and white, Landscape orientation PCL-GL/2 language picture.) An MLAB .PS plot-file can be converted to a so-called 'Encapsulated Postscript' file suitable for embedding in a "document" file such as an MSWord file, or a .tex file by editing the file to change the Landscape orientation of the MLAB graph to a Portrait orientation and to respecify the size of the picture. This is done by editing the MLAB graphics file as follows: 1- "open" the plot-file (MLABP0.PS say) with an ASCII text editor (or with the MLAB command: EDIT FILE MLABP0.PS), 2- goto to the fifth line in the file, that contains the text defining the bounding box given in 'point'-units (1 inch = 72 points) that encloses the graphical image: %%BoundingBox: 19 19 593 773 3- exchange the order of the last two numbers corresponding to the width and height in point-units, so that the line reads: %%BoundingBox: 19 19 773 593 (This changes the picture to have the size appropriate for "portrait orientation".) 4- goto the 32nd and 33rd lines of the file, that read: 612 0 translate 90 rotate and insert a %-character at the beginning of these two lines, leaving: %612 0 translate %90 rotate (Lines in PostScript files beginning with a SINGLE percent (%) character are treated as comments and ignored. This drops the rotation of the picture that MLAB inserted to leave it in "portrait orientation".) 5- save the file to disk with the name MLABP#.EPS (not .PS) where # denotes an integer of your choice, using the same integer as the starting .PS file is generally appropriate. The 'encapsulated PostScript' file, thus created should be saved with the filename extesion .EPS. It can be "imported" to MicroSoft Office (Word, PowerPoint, Excel) or TeX 'documents' (i.e. files). For example, to add the MLAB graph in the file MLABP0.EPS to an MSWord document, position the text cursor in the MS Word document where the graph is desired, goto the "Insert" menu, select "Picture" from the drop-down menu, select the "FromFile" option, select the MLABP0.EPS in the resulting FileSelect dialogue box, and then select "Convert File From Encapsulated PostScript". -------- 7 - .lst files: ASCII files containing MLAB data names and data. The MLAB PRINT command: PRINT [name1,name2,....] in generates an ASCII text file named 'filename.lst' in the current working directory containing the MLAB data names name1, name2, etc. and their corresponding values. If the mlab control variable NAMESW = 0, then the MLAB data names are suppressed in the output file. This provides a convenient way, for example, to "export" an MLAB matrix to another computer program that accepts ASCII data files. Note, the MLAB command: PRINT FILE sends a command to the local printer, to print the named file in the current working directory. -------- 8 - .sav files: A .sav file is a binary file containing "saved" MLAB data names and values. The entire current state of MLAB, including all control variables and user-created curves, windows, functions, matrices, scalars, etc., can be saved in a .sav file in the current working directory by the command: SAVE IN The saved state of MLAB can then be restored at any other time and in any other MLAB session by typing the command: USE The SAVE command can also be used to save specific MLAB data structures, such as an MLAB graphic window named Q and a scalar vaule named B by listing the specific data items to be stored; for example: SAVE Q,B IN The window can be restored in a later MLAB session by typing the command: USE .SAV files are binary files; they can not be edited directly with ASCII editors and are not exchangeable across different types of computers; i.e. a .SAV file from Windows MLAB can not be easily transferred to a non-Intel Macintosh version of MLAB due to the "endian" conflict. The pre-defined .sav-file DW.SAV defines the elements of the default MLAB graphics window, W, and provides an example of a .sav file. DW.SAV is generated by giving the MLAB commands (we do this via a do-file): WINDOW 0 TO 10, 0 TO 10 ADJUST WNICE IN W; XAXIS 0:10!6&'0 LABEL 0:10!6 LABELSIZE .015 FFRACT OFFSET (-.01,-.025) \ FFRACT FORMAT (-3,5,0,0,2,0) PT UTICK IN W; YAXIS 0&'0:10!6 LABEL 0:10!6 LABELSIZE .015 FFRACT OFFSET (-.09,-.01) \ FFRACT FORMAT (-3,5,0,0,2,0) PT RTICK IN W; FRAME COLOR VIOLET IN W; IMAGE COLOR BLUE IN W; SAVE W IN DW When drawing in MLAB without specifying the target MLAB "window", the default MLAB-"window", W, will be used. MLAB obtains W by USE-ing it from DW.SAV. ------- 9. - Printing Files on a Windows system. The MLAB command: PRINT FILE sends a command to the local printer, to print the named file in the current working directory. The PRINT FILE works for ASCII files, such as .dat or .lst files, and it also works for .lj files if you have a directly-attached HP PCL-language printer (most printers understand the PCL language.) This also works for .ps files if you have a directly-attached Postscript-language printer. (If not, you may need to use a web-browser to view .ps files generated by MLAB. You may be able to print them via the web-browser program. Also, if MSWord is properly programmed with the analog of the Ghostscript Postscript to PCL converter, you may be able to view a .ps file via MSWord.) Also, you can send a file to your printer to be printed with the command "COPY LPT1:" given in a DOS command window. The file must be an ASCII text file, or in a native language of the printer. ======================== Some More Information about Using MLAB 1. How to draw and plot a 3-D surface picture. You may want to see a surface (a graph of some function f(x,y), or a parametrically-defined surface of the form (x(s,t), y(s,t),z(s,t)) for example.) When that surface is the surface of a single-valued function, a useful way to "see" it is to look at a corresponding contour map. See the contour-map example: conex.do, found in the MLAB examples directory reached from the MLAB start-up menu. A "fancier" way to view a surface is to generate a perspective 3D view of the surface. An example of how to do this is found in the example do-file: torex.do located in the examples sub-directory (generally this is /Users/[username]/Desktop/mlab/examples/). The DRAW command described earlier for ordinary 2D graphs can also be used to create 3D perspective views of 3 dimensional data. The simplest 3D graph is a simple plot of a set of 3 dimensional points in which each point is drawn with a specified point-type symbol. For example, consider a set of 100 points with random coordinates. Such a set can be created with MLAB with the following command: M = SHAPE(100,3,RAN ON 0^^300) Then the command: DRAW M POINTTYPE DOT3D LINETYPE NONE creates the 3D window, W3, with a dot at each point given in the data matrix, M. Other 3D graphics point-types include: CROSS3D - this draws a 3D cross at each point, "char" - this draws the given quoted ASCII character (such as "x") at each point.. When you enter the command: VIEW MLAB displays a default 3D perspective view of the points. The default 3D perspective view is a view of the data as it would appear in the viewfinder of a camera placed at a suitably-chosen position and pointed in a suitably-chosen direction. The default position and direction of the "camera" are determined as follows: first, find the limits of the bounding box for all 3D points, lines, curves, and surfaces: (xmin<=x<=xmax, ymin<=y<=ymax, zmin<=z<=zmax) with box-dimensions x1=(xmax-xmin), y1=(ymax-ymin), z1=(zmax-zmin) on the sides parallel to the x,y, and z-axis, respectively. The center of the box is at (xcenter=xmin+x1/2, ycenter=ymin+y1/2, zcenter=zmin+z1/2). When the VIEW command is first given, the initial view drawn is that seen in the 'viewfinder' of a camera positioned at (xcenter,ymax+y1,zmax) with its lens pointed in the direction which results from right-hand-screw rotating a unit vector which is initially parallel to the z-axis by 105 degrees about the x-axis. The camera's initial viewing angle is 90 degrees. After MLAB displays the initial 3D perspective view, a double-arrow prompt, >>, is printed. At this stage, MLAB is awaiting a 3D view command. Striking the Enter key without giving a 3D viewing command will terminate the viewing command input at once, and return to the usual MLAB command prompt, *. There are eleven 3D perspective view commands that modify the camera position and pointing direction. These are: DOLLY K - which moves the camera forward in the view direction TRUCK K - which moves the camera to the right of the view direction RAISE K - which moves the camera up from the view direction PAN A - which rotates the camera about the vertical axis TILT A - which rotates the camera about the horizontal axis TWIST A - which rotates the camera about the viewing axis TRACK - which rotates the camera so as to point to the origin TURN A - which right-hand-screw rotates the camera about the center of the 3D bounding box (x1,y1,z1) ZOOM A - which changes the angle of view ORIGIN - which moves the camera to the origin, looking up the z-axis RESET - which automatically returns the camera to the initial view In these commands, A is an angle in degrees [0:360] and.K is a number of "relative-box" units such that the main diagonal of the bounding box is 1 relative-box unit. Fore example, DOLLY -.5 would move the camera backward in the viewing direction by .5 relative-box units. There are also 3D graphics commands for adding or removing graphical 'elements' of the 3D MLAB "window"; for example, the bounding box can be drawn with the command: BOX or can be erased with the command: NO BOX In addition to the commands listed above, there are more than 75 other 3D graphical commands for manipulating the 'elements' of the 3D perspective MLAB window. See the MLAB Reference Manual and MLAB Graphics Examples Manual for further discussion. MLAB has seven line-types for 3 dimensional graphics. These are: NONE NEEDLES SEQUENCE ALTERNATE MARKER NET HIDDEN As seen in the example above where we drew points using LINETYPE NONE, the line-type NONE draws no line segments. The NEEDLES line-type draws line-segments from each point in the 3D data matrix, say (x[i],y[i],z[i]), to the bounding box floor at (x[i],y[i],0). The SEQUENCE line type draws line-segments from the i-th data point to the (i+1)-th data point for all the 3D data points. This line-type is of use when drawing the 3D perspective view of a space curve. The ALTERNATE line type draws line-segments between every other pair of 3D data points; i.e. between the first and second, third and fourth, fifth and sixth, seventh and eighth data points, etc. The result of a MARKER line-type is similar to the MARKER line-type used for 2D data. The values of the first row of the 3D data matrix define a 'marker' value. As line drawing proceeds sequentially from a 3D data point to the following 3D data point, if the marker value is encountered in column 1 then no line-segment is drawn and the sequential drawing of line-segments is started anew until the next marker value is found. The line types NET and HIDDEN are used for graphs of 3D data in which the data describe a surface. The surface may be an explicit function of two variables with data {(x[i],y[j],f(x[i],y[j])), for i=1,2,...,nx and j=1,2,...,ny} or the surface may be defined parametrically, in the form {(x(s[i],t[j]),y(s[i],t[j]),f(x[i],t[j])), for i=1,2,...,nx and j=1,2,...,ny}. For an example you may define a function of two variables: FCT F(X,Y) = (x^2+y2)/2 + x^2*y-y^3/3 and then generate a grid of x and y values: M = CROSS(-2:2:.2,-2:2:.2) and then evaluate the function F at each grid point: M COL 3 = F ON M and then graph the data with the NET line-type: DRAW M LINETYPE NET VIEW the resulting 3D perspective graph shows an image resembling a wire mesh with each point of the grid connected to its four nearest grid neighbors. The HIDDEN line-type for 3D perspective graphs corresponds to the NET line-type except that "quads" are filled-in with color and parts of "quads" on the surface that are obscured by intervening quads of the surface are not seen! The HIDDEN linetype is demonstrated in the TOREX.DO do-file in the examples subdirectory. The command CMD3D can be used to specify 3D graphics commands; this is particularly useful in do-files. You simply give a sequence of desired 3D graphics commands deparated by semicolons [;] in a quoted-string as the argument of the CMD3D 'function'. For example, CMD3D("TRACK; DOLLY .5") given in a do-file (or even at 'top-level' before the VIEW command) will have the same result as typing the commands TRACK; DOLLY .5 at the <<-prompt. You will want to experiment and read the MLAB Reference manual about all the 3d, hidden-surface, and other viewing commands and options. If you are "plotting" an MLAB hidden-surface picture, you should use PLOTDEV = PSCL (PSCL stands for Postscript-color-landscape.) This will render your picture correctly on both a color PostScript printer, and on a black and white PostScript printer (via grey-scale dithering matching the specified colors.) Using PLOTDEV = LJ2L specifies that a "raw" plot file for a PCL-language printer be created. A PCL-language plot-file cannot (currently) be used to render an MLAB hidden-surface picture. -------------