Filename: readme.xm                   Revision Date: July 7, 2017
       Downloaded Trial MLAB Installation and Operation Guide

This is the installation guide for the downloaded PowerPC, G3, G4, and
G5 Macintosh OS X version of MLAB.  This OS X version of MLAB is a
native OS X PowerPC 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/Vista/Win7, Intel-Linux, Motorola Macintosh OS7/8,
PowerPC Macintosh OS9, Intel Macintosh OS X, 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  (out-of-print)

The price of the three available manuals is $99, plus shipping.  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 manuals 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

When you download MLAB, a file called MLAB.zip is transmitted to your
computer by your browser and unpacked into a directory called MLAB
containing the various files and subdirectories that constitute the
MLAB package.  (A directory is usually called a 'folder' in Macintosh
parlance.)  For the Safari browser, the default location where this
MLAB directory is placed is in /Users/[User name]/Desktop/; here [User
name] denotes your home directory.

It is possible to tell your browser to place the MLAB directory in
some other location, or you can manually transfer the entire MLAB
directory tree to any location of your choice.  If you do not know how
to do this, then you must settle for the default location.  When
MLAB.zip is downloaded and unpacked, a directory icon (a picture of a
"folder" labelled MLAB) is placed 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 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:

	readme.xm      (this file)
        mlabfiles.txt  text file containing more information about
                       running MLAB
	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 28 do-files for study and tutorial use:
	  mlabex.do     lrcex.do      windkex.do      graphex.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 PowerPC, 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 GUI 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.]

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 can not be run after this,
unless it is re-registered there.

3. Install MLAB from the diskettes, 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 <filename> after the MLAB command prompt,
where <filename> is the name of the file to be edited.  After editing
and saving the file with EditFile, terminate the EditFile 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 <filename>.  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.]

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.

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 be 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
<return>, 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 <filename>' in MLAB.  You
can also type 'DO <relative path/filename>' 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 <filename>

   where <filename> 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 and nor written
         to the log-file.

     - dostep
         dostep controls the execution of successive statements in the
         DO-file.  If dostep = 0, the DO-file executes without stopping,
         except where PAUSE, VIEW, KREAD, and other statements requiring
         user input appear.  If dostep = 1, the DO-file executes one
         statement at a time, waiting for the user to press a key on 
         the keyboard before proceeding to the next statement.

     - casesw
         if casesw = 1, then all names used in MLAB commands are case 
         sensitive; i.e. MLAB distinguishes upper case characters from 
         lower case characters in all names of variables, matrices, 
         windows, functions, etc. if casesw = 0, then no distinction is 
         made between upper case and lower case characters.

2. MLAB data in ASCII text can be read from .DAT files by issuing the
   MLAB READ command:
 
         <matrix name> = READ(<filename[.DAT]>,nrows[,ncols])

   where <matrix name> is the name of a matrix to which the array of
   numbers to be read is to be assigned; <filename[.DAT]> 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 <filename[.SAV]>
 
   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 <filename[.SAV]>

   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 <filename[.LST]>

   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 <filename[.PS]>]

   creates the named file and writes ASCII text PostScript commands 
   depicting graphs in the named MLAB windows to the named file.  
   If no MLAB window names are provided in the command, PostScript 
   command depictions of all unblanked MLAB windows are written to
   the file.  If a filename is not provided in the command, a file 
   named mlab#.ps, where # is the first integer in the set 
   {1,2,3,...} selected so as to avoid a name conflict with files 
   in the working directory.

   The MLAB system variable PLOTDEV determines the type of graphics output.
   By default, PLOTDEV equals PSL and the PLOT command generates files
   for black and white PostScript output. If PLOTDEV equals PSCL, then
   the PLOT command generates files for color PostScript output.  If
   PLOTDEV equals HPLJ, then the PLOT command generates files for 
   Hewlett-Packard LaserJet output.

   If a PostScript or Hewlett-Packard printer driver and lpd printer
   demon is properly configured, the following Unix command may be
   used to send the file MLAB0.PS to the printer:

         lpr MLAB0.PS

 
6. the MLAB file MLAB.HLP contains descriptions of most MLAB built-in 
   functions and statements.  By typing "help" after the MLAB 
   prompt, you will get general information about MLAB, and you can
   follow the directions to get more specific information.  Alternately,
   you can type: help "topic"
   where "topic" is a quoted string name of an MLAB built-in function
   or statement, the corresponding description is read from the MLAB.HLP
   file and printed to the MLAB terminal window.  Unfortunately, the
   file MLAB.HLP is not complete.  Thus you should have a copy of the
   MLAB Reference Manual to make best use of MLAB.

  
7. finally, MLAB always creates a log file of all commands and responses 
   in an MLAB session called MLAB.LOG.  MLAB0.LOG, MLAB1.LOG, and MLAB2.LOG 
   are the log files for the previous three MLAB sessions.

These files will all reside in the directory in which the MLAB
application file is located, unless the control variables FILEDIR
and/or DOFILEDIR are set to specify particular directories.


TECHNICAL SUPPORT

Please contact Civilized Software (301-962-3711); or email us at
csi@civilized.com if you have any problems.


------------

INTRODUCTION TO USING MLAB

Here is a brief introduction to using MLAB.

1. MLAB as a calculator.
========================

MLAB can be used as a calculator.  As with most computer languages, +
is used for addition, - is used for subtraction, * is used for
multiplication, / is used for division, and ^ is used for
exponentiation.  Numbers may be entered as integers, floating point
numbers with a decimal point, or in scientific notation using the
letter E before the exponent.  All numbers are converted to 64-bit,
double precision, floating point numbers.  Note that MLAB does not
directly support complex numbers.  The precedence of operations
evaluated from right to left in an expression, from highest precedence
to lowest precedence, is: exponentiation, division, multiplication,
subtraction, and addition.  Parentheses (), square brackets [], and
curly braces {} may be used pairwise to alter the natural order of
evaluation. The variable PI is automatically defined in MLAB to be
3.14159265.

For example, following the asterisk prompt, type:

	6.02E23*1*10/(.0812*276)<Enter>

where <Enter> 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 <Enter>, 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)).

(Currently, arithmetic exception handling does not work on
Intel-Macs.)

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
<process-number>", 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.


		  OS X POWERPC MACINTOSH MLAB REGISTRATION
----------------------------------------------------------------------------

Please send the following user registration information to Civilized
Software Inc., 12109 Heritage Park Circle, Silver Spring, MD 20906, (USA);
or call (301) 962-3711 or send email to csi@civilized.com.
This information is required in order to send you updated versions of
MLAB, and in order to be registered for telephone support.

	  name:____________________________________________________

   institution:____________________________________________________

       address:____________________________________________________

city,state,zip:____________________________________________________

       country:____________________________________________________

     telephone:____________________________________________________

	e-mail:____________________________________________________


comments and suggestions:_________________________________________

__________________________________________________________________

__________________________________________________________________

__________________________________________________________________

__________________________________________________________________


Please list the name and address of people who would be interested
in MLAB:

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------

------------------------------------------------------------------












