file: shortmlab.intelmac.txt            date: January 26, 2019 

This is information for installing and running MLAB on an Intel
Macintosh or a PPC Macintosh with OSX. You may want to print this text
and keep it for reference.  Some details differ for MSWindows and for
Linux, but this information is still valuable.

A Quick Example of using MLAB:
------------------------------

When you run MLAB, a "darwin" console window is put on the screen, and
a smaller "start-up menu" window is displayed in which you must make a
selection to look at examples or go to "top-level" MLAB.

Actually, the 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 by typing the commands
shown below.

 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'?--it means
from 1 to 10 in 100 steps.)

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 &'?)

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 uses 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 a wide variety of chemical kinetics and
physiological and compartmental and other models 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 at www.civilized.com that offers the
option to download the MLAB manuals in PDF format.

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



There are manuals available for MLAB from Civilized Software. 
These are:

		MLAB Reference Manual 
		MLAB Applications Manual 
		MLAB Graphics Examples
		MLAB Users Guide 

All these manuals are available as pdf-files at www.civilized.com.
The first three can be provided in printed form for $99 plus shipping
from Civilized Software, Inc.  These .pdf files or 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 versions of the MLAB Reference Manual and the MLAB
Applications Manual can be downloaded for free from the Civilized
Software website, www.civilized.com.  You should obtain and 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.


Installation Directions

This is the installation guide for the Intel-Mac OSX version of MLAB.
(MLAB also exists in DOS 640K overlay, DOS extended-memory flat model,
16-bit Windows 3.1, 32-bit Windows 95/98/NT/2000/XP, Intel-Linux,
Motorola Macintosh OS 7/8, PowerPC Macintosh OS9, PowerPC Macintosh
OSX, and several UNIX versions.


GETTING MLAB:

A downladable copy of MLAB for Intel Macintoshes running OSX (G5's,
mac-mini, mac-pro, etc.) is available at www.civilized.com.  It is a
"native" (not emulated) program.  This file is called mlabi.zip and it
is about 1 megabyte in size.  It should take from a second or two to a
minute or two to download (There are also versions of MLAB for PPC OSX
Macs, and for earlier OS-9 PPC Macs, and for yet earlier OS-8,7
Motorola Macs.)

Before you download MLAB for an Intel-Mac, you will want to look at
the short Introduction to using MLAB found at www.civilized.com (You
should print a copy for later reference.)

The version of MLAB you will obtain is the complete program with an
expiration date.  After you pay for it and register it, it will then
have an unlimited lifetime.  On-line help about MLAB functions and
commands is available (by typing "help" in MLAB), and there are MLAB
manuals in PDF format that can be downloaded from www.civilized.com.


DOWNLOADING AND INSTALLING MLAB:

When you click in your web-browser to download the OSX-native
Intel-Macintosh MLAB program, a Macintosh archive file called
mlabi.zip will be downloaded to your computer and "unpacked", as
described below.  The compressed file mlabi.zip contains an mlab
directory with the mlab application file and related files.

When mlabi.zip is downloaded using the Safari web-browser, a copy of
the file mlabi.zip is written to /Users/[username]/Downloads, and then
the downloaded file mlabi.zip is "automatically" unpacked in the same
directory, creating a sub-directory called mlab containing the various
MLAB files.

(Note the file mlabi.zip is usually deleted, leaving just the mlab
directory containing the mlab application and related files in
Downloads/.)

After you have used Safari to download and unpack mlabi.zip, then
using the Finder, locate the mlab directory in the Downloads directory
and drag the mlab directory to the Desktop. This will move the
sub-directory mlab, and its contents into the
/Users/[username]/Desktop/ directory, and an icon for this directory
will be immediately available for you to access MLAB.

[If the web-browser does not automatically unpack the mlabi.zip
compressed file, then locate the mlabi.zip file using Finder and
double click on the mlabi.zip file icon to unpack the mlab program and
related files.  A directory named mlab then appears in the directory
where the mlabi.zip file was located.  Again, you should drag the mlab
directory to the Desktop to move the subdirectory mlab/; the mlabi.zip
file may then be discarded.]

The installation of MLAB is now complete!


RUNNING MLAB THE FIRST TIME:

To run mlab for the first time, double click on the mlab directory
icon.  A Finder window will then appear showing the contents of the
mlab directory.  IF YOU JUST DOUBLE-CLICK ON THE mlab application name
(titled "mlab") in the list of files showing in the Finder window,
(The mlab application icon appears before the name "mlab" as a small
rectangular Terminal screen with "exec" printed in green letters at
the upper left corner) then in later versions of Mac OS X an alert dialog
window will appear stating:

   "mlab" can't be opened because it is from
   an unidentified developer (or a similar message.)

In this case, just click the OK button in the alert dialog window,
and start again.

To run MLAB the first time, you must RIGHT-CLICK on the MLAB
application name!  (With a touch-pad, you must hold the `control key'
down and click on the touch-pad).  When you right-click, a menu will
appear.

You must select "Open with" (DO NOT SELECT "Open"), and slide right to
select Terminal.app, and then click that selection in the drop-down
menu.  An alert dialog window will then appear stating:

   "mlab" can't be opened because the identity of the
   developer cannot be confirmed.

You should then click "Open".  The MLAB program will then run; the
MLAB terminal window will appear (this is just a so-called Darwin
window).  You will be asked to enter the principal MLAB user's name;
do so.  You will then be given a menu that allows you to look at some
MLAB examples, which you may wish to do.  When you are done, you must
goto "top-level" where a * will appear as a prompt for a command.
Enter the command "exit" to exit.  FROM THIS POINT FORWARD,
DOUBLE-CLICKING ON THE NAME MLAB IN THE LIST OF FILES OF THE MLAB
DIRECTORY PRESENTED BY THE FINDER WILL RUN MLAB WITHOUT FUSS!  (On
subsequent executions of the mlab application, the security alert
dialog windows will not appear.)



RUNNING MLAB THE SECOND AND SUBSEQUENT TIMES:


To run MLAB, display the MLAB directory in a Finder window,
and double-click on the MLAB application name in the displayed
list of files.

An MLAB Terminal window will then appear with the MLAB application
running therein.  On the first execution of mlab, you were prompted to
enter a user name.  This user name will appear in the MLAB terminal
window henceforth.  Starting on the second day, you will be shown your
MLAB id value and asked to register MLAB; until you have an MLAB
registration number (also called an authorization key), you should
just enter 0, as directed.

Then, in addition to the MLAB terminal window, a menu with options for
running MLAB demonstration scripts (called do-files), going to
top-level MLAB, and displaying tips on using MLAB.  Select the first
option to look at examples, and follow directions in subsequent menus
and text printed to the terminal window.

After executing some MLAB demonstration do-files, select the option:
"Go to top-level".  MLAB then prints an asterisk in the terminal
window and requires you to enter a command.  You can now enter
commands into MLAB, and you can also build a do-file of such commands
by typing: edit file [filename].  When you are done, you can then
terminate the MLAB application by typing EXIT followed by the return
key, or by clicking on the red close button at the upper left corner
of the terminal window.

When MLAB terminates, depending on the preferences set for the
Terminal application, the Terminal window may remain on the computer
screen.  You can change the Terminal application preferences so that
the Terminal window automatically disappears when exiting mlab by

 1. clicking on the word Terminal at the top of the screen, 

 2. selecting Preferences... in the resulting drop-down menu, 

 3. clicking on the Profiles icon (or Settings icon) at the top of 
  the resulting Profiles dialog window,  

 4. clicking on the tab labelled Shell below the top row of
  icons, and 

 5. selecting "Close the window" in the pop-up menu that appears
  below the "When the shell exits:" label, and clicking on it.  
  [Note, there are many options and features to the Terminal preferences
  that you can select to customize the Terminal window in which mlab
  runs, including text font, size, foreground and background colors,
  etc.]

 6. After modifying the Terminal preferences, click on the red close
  button and the modifications will be saved for future mlab sessions.

Also when MLAB exits, a record of all commands and responses will be
written in your "working directory"; this file is called mlab.log.
You can find your working directory printed out in the MLAB terminal
window whenever you run MLAB (it is "/Users/[username]/"); you can
view the files in your working directory by typing the MLAB command
"type dir"; this will show the "current" mlab log-file mlab.log, as
well as the previous MLAB log-files named mlab0.log, mlab1.log, etc.
You CANNOT printout the current mlab log-file within MLAB, because it
is "open" and being written into; however, you can printout the
previous mlab log-file by typing "type file mlab0.log". (You can
also print any file at any time with the command "cat" in a Darwin
terminal window (not the MLAB terminal window).)


CREATING AN ALIAS ICON FOR MLAB:

It will probably be convenient for you to create a so-called
alias icon for MLAB on your Desktop; this will allow you to
run MLAB without the Finder, by just double-clicking on this
alias icon.

To create an alias icon on your desktop for executing the mlab
application, 

  -double click on the mlab directory on the desktop that was placed
   there when you placed the MLAB directory in your Desktop
   directory.  This displays the contents of the MLAB directory.

  -right-click on the mlab application name appearing in the Finder
   window; and 

  -select "Make Alias" in the pop-up menu.  

A new entry in the mlab directory displayed by the Finder window will
appear labelled "mlab alias".  Drag and drop the "mlab alias" entry to
your desktop.  This will create an icon consisting of a black terminal
window labelled "mlab alias".

Then mlab can be executed simply by double-clicking on the mlab alias
icon you have created.  [Note, on some later OS X systems,
double-clicking on the resulting "mlab alias" icon merely opens a
Finder window showing the contents of the mlab directory.  In that case,
you can obtain a properly functioning mlab alias as follows.

  -right-click on the mlab alias icon, and
   select "Get Info" from the pop-up menu. Another window
   titled "mlab alias info" will appear.
  
  -click on the wide button labelled "Select New Original..." in this
   window.  

Yet another Finder window will appear with the heading 

 --Select the item you want alias "mlab alias" to open-- 

Click once on the mlab application icon in the list of files shown,
and then click on the right lower-corner button labelled "Open".
The Finder window will then disappear, and you must then
click on the red close button of the mlab alias info window
that is showing.


========================



Before you run MLAB, it is important(!) that you print out this file
or the file intelmac.readme found in the MLAB directory on your
desktop. The file intelmac.readme contains these directions plus other
important information on using MLAB, such as how to respond to the
initial registration request, etc.

When MLABI.zip is properly downloaded and unpacked, a directory icon
(a picture of a "folder" labelled MLAB) will appear on your "Desktop".

(The MLAB directory is now available to the user that owns the Desktop
directory containing MLAB; it is not available to other users of your
Mac OS X system unless you take appropriate steps to make MLAB
globally accessible.  To do this you need to know some basic Mac OS X
and unix commands.  In order to make MLAB available to all users, you
need to run a terminal program and type the commands: 

  su root (and enter the root password)
  chmod 711 /Users/[User name]/Desktop
  exit

Basically, all the directories in the path /Users/[User name]/Desktop/MLAB
need to be given execute permission for everybody.  Usually the only 
directory that does not have such execute permission is the Desktop
directory.)


==============================


We will assume in the text below that the MLAB directory is in
/Users/[User name]/Desktop.

The files that have been established in the MLAB directory are:

	intelmac.readme    (this file)
	init0.fil          the secondary MLAB initialization file
	token.fil          the MLAB token file
	dw.sav             the MLAB defaultwindow save file
	init.sav           the MLAB initialization file
	mlab.hlp           the MLAB help text file
	gxfonts.0          the MLAB stroke font file
	dimer.do           an example MLAB do-file for study
	startup.do         an automatic demonstration do-file
	startup.dat        a data file for startup.do
	mlab               the MLAB executable program
        
In the Examples sub-directory are 27 do-files for study and tutorial use:
		mlabex.do     lrcex.do      windkex.do
		kmestex.do    hhdoex.do     dimerex.do
		holfex.do     enzymex.do    gcrex.do
		payex.do      liglex.do     ttestex.do
		vorex.do      centriex.do   dcaex.do
		djiaex.do     snsptex.do    laserex.do
		conex.do      ctnryex.do    henonex.do
		minmodex.do   ndiskex.do    fnpex.do
                magnetex.do   torex.do      mlabex1.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.



RUNNING MLAB
 
After double clicking on the MLAB application name or its alias, MLAB
will start to run.  First a moveable, scrollable, and resizeable
window titled "Terminal - mlab" will be put in the center of the
screen.  (This is a "Darwin" terminal.)  

All subsequent MLAB dialog will appear in this terminal window.  MLAB
prints the date, time, version information, MLAB path, and the owner's
name in the terminal window, and displays a small menu from which you
either execute examples or go to top-level MLAB where you can execute
MLAB commands and/or DO-files. (DO-files and data-files must be in
your "working" directory unless you set FILEDIR or DOFILEDIR
appropriately.)  It is recommended that you run examples the first
times that you try MLAB.

Finally, you can also run MLAB by starting a Darwin window (you should
arrange to get the Darwin terminal program to run as a startup
program, if you are going to use Unix commands to run MLAB.  This is
how we do it.)  In the Darwin window, you can run MLAB by typing the
filename for the MLAB executable.  This filename must, of course, be
appropriately prefixed by any needed path information.  It is
convenient if you change your PATH environment variable to include the
path to mlab.  The mlab executable will normally be 
/Users/[User name]/Desktop/MLAB/mlab. [Running MLAB from a Darwin
window is the preferred way to run MLAB because you can first
do a cd command to establish the working directory that you desire.]

When MLAB is running in a Darwin Terminal window, you can customize
various aspects of the Darwin Terminal window, such as the font, font
color, font size, and the number of lines of history to be stored in
the command buffer, by clicking on the Terminal menu and selecting
Preferences from the drop-down menu.  A given set of such preferences
can be saved for subsequent MLAB sessions.


REGISTERING MLAB

When you first run MLAB, you will be asked to enter the name of the
principal MLAB user, which is recorded so that it may be typed-out
each time MLAB is run subsequently.

Also you will be asked to register MLAB with Civilized Software.  In
particular, you will be asked to enter an authorization key-value to
register MLAB, or to enter zero if you do not (yet) have your
authorization key value.  (If you have a limited-lifetime trial
version, as you get when you download MLAB from www.civilized.com, you
will be prompted to purchase MLAB; following which you can obtain an
authorization key and register it.  If you have already purchased
MLAB, you need to contact Civilized Software at csi@civilized.com to
obtain your authorization key-value. If you have not yet purchased
MLAB, you need to contact Civilized Software to do so.

When you 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.


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.


The Executable Directory and the 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.
Generally, this directory is /Users/[username]/Desktop/mlab/.  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, 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.

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









USING DO-FILES
                  
You should quickly get in the habit of constructing do-files using
your favorite text editor (vi, emacs, TextEdit, 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/[Username]/Desktop/MLAB where the MLAB executable is stored.

A file can be edited or created using the TexstEdit text-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 created or edited.  If the named file does not exist, MLAB will
prompt the user to specify whether a new file should be created.
Ordinarily, the user responds by pressing the C key to create the
file.  Then a new window will appear. This is a TextEdit window.
Note, this TextEdit window may be obscured by the MLAB terminal
window.  In that case, it will be necesary to move the terminal window
where MLAB is running to the side and click on the title bar of the
TextEdit window to bring the TextEdit window to the front.

You may use the TextEdit program to create and save a text
file.  Usually this text file will be an MLAB do-file or a
data file.  An MLAB do-file is just a "script" of MLAB commands
and it should be saved with the name xxx.do (i.e. the extension
.do should be used).  A data file generally just contains arbitrary
text and, in particular, numbers which can be read with the
READ command in MLAB; a data file should use the extension
.dat in its file name.  

You must be sure you save your files in the appropriate directory, and
that you have FILEDIR and DOFILEDIR set appropriately in MLAB.
Leaving the editor program running once you have started it, is
considerably easier and quicker than quiting each time you go back to
MLAB, all you need to do is edit the file that is showing and save it.

Normally, running TextEdit with the EDIT FILE xxx.do command will
present a "plain" TextEdit window, and when you save the file
xxx.do (by selecting "Save" from the drop-down File menu), it will
be saved in your working directory as a plain text file with the
name XXX.DO.  If you run TextEdit directly from the Finder or
otherwise, TextEdit will assume you are creating a so-called .rtf
file.  You must click on "Make Plain Text" in the Format drop-down
menu, and then, when you save the file, you will see a window in
which you must (1) specify the filename, (2) specify the directory
in which you wish this file to be saved, (3) uncheck the option
"If no extension is provided use .txt".  (The UTF-8 format is
correct.)

You can alternatively run any editor you choose directly and use it
side-by-side with MLAB.  (We run MLAB by running the emacs text editor
and using it to create and modify do-files and then switch to the MLAB
window, from time to time, to execute a new or changed do-file.)


[Using emacs]

The emacs program is very powerful, and is correspondingly complex,
however, you can easily learn enough to use it effectively.  ('emacs'
stands for 'Editing MACroS'.)

Normally when you run emacs, you have the file you want to edit
showing in the emacs window.  You can bring in any file you want for
editing by typing ^x ^f (where ^ is the ctrl key); then emacs will
prompt you for the filename. You can change text in a file by using
the arrow keys and esc v (or page-up in a window) and ^v (or
page-down in a window) to position yourself and then just type
to insert text. ('esc' denotes the escape key, and ^k denotes holding
the 'control' key down and typing 'k' (or whatever.) Thus esc v
specifies two successive key-strokes, while ^v specifies a "chord" -
hitting v while "ctrl' is down.)

[If you see that your typing is REPLACING text, then you are in
'insert-replace' mode - hit the Insert key to toggle out of (or into)
this mode.] You can delete characters backwards by using the backspace
key, and delete characters forwards by using the delete key.

You save your edited file to disk by typing ^x ^s, and you exit the
emacs editor by typing: ^x ^c.

There is a LOT more to know about emacs, such as esc % to substitute
one string of characters for some other specifed string, ^g to 'reset'
emacs, and on and on and on.  You should use google to find an emacs
manual and print it for study.

After editing the file with Emacs, terminate the Emacs application
with the keyboard key combination Ctrl-X Ctrl-S to save the file to
disk, and Ctrl-X Ctrl-C to terminate the emacs application, and MLAB
will resume.  

Of course, you must be sure you save the do-files in the appropriate
directory, and that you have FILEDIR and DOFILEDIR set appropriately.
Leaving the editor program running is considerably easier and quicker
than quiting 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 terminal window, you can use a cd
command to select a working directory of your choice, and then run
MLAB by typing: /Users/[User name]/Desktop/MLAB/mlab, then your
working directory is whatever you have chosen by explicitly cd'ing.

If you run mlab by clicking on the mlab alias icon then your working
directory is /Users/[User name]/.  

If you run mlab by double-clicking on the MLAB filename in a Finder
window, then your working directory is /Users/[User name]/.

If you want some other directory to be your working directory after
you run MLAB, then the MLAB string variable "FILEDIR" should be
initialized to the character string specifying your desired working
directory as described below; it can be changed at will to specify any
other directory you may wish to access.

When the EDIT FILE command is used to run the TextEdit program, 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".

After you have created 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 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.


MOVING MLAB TO ANOTHER COMPUTER

You can install MLAB on as many computers as you wish, but if you want
to register MLAB with an unlimited lifetime on a computer that would
exceed your licensed number of registered copies, you will be required
to uninstall MLAB from an existing registered computer.  Directions on
how to proceed to uninstall MLAB are as follows.

1. Call or email Civilized Software and notify us that you are moving
your registered copy of MLAB to a new machine.

2. Run MLAB on the current machine it is installed on, and enter the
command "-INSTALLMLAB" and record the uninstall code that is reported
to you.  This copy of MLAB is now disabled and can not be run after
this, unless it is re-registered there.

3. Install MLAB 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.

-------------------------------------------------------------------------
			      
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, then
         DO-file statements are neither printed to the screen nor written
         to the log-file.

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

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

2. MLAB data in ASCII text can be read from .DAT files by issuing the
   MLAB READ command:
 
         <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 LJ2L, then the PLOT command generates files for 
   Hewlett-Packard LaserJet output.

   If your printer is properly configured on your Mac OS X system,
   then the following Unix command may be entered in a terminal window
   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.

   When you exit MLAB, the MLAB log-file of that session will be saved
   in the working directory specified by the value of the FILEDIR
   directory string.  If this string is empty, then the working
   directory at the time MLAB was started will be the directory where
   the MLAB.LOG will be saved.

   In general, all PRINT, SAVE, RESAVE, and PLOT output files and all
   REUSE, USE, DO, and REUSE input files will be either created or
   looked-for in your current working directory as defined by the
   initial working directory when MLAB was run, or by the value of
   FILEDIR, if it has been set.
   

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 a numerical result
will be generated (go try 2/0, -4/0, and 0/0) that allows any
computation to continue.  (You will receive a warning about such
exceptions.)  If an "overflow" occurs, the largest correctly-signed
computational value (1.797..E308 or -1.797..E308) will be generated
(try: 1.5e167 * (-2.3e201)).

Arithmetic exceptions are handled in MLAB by detecting and handling
the signals generated by the operating system when such exceptions
occur.  


2. General Computation in MLAB
==============================

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)
	
There is an extensive selection of basic built-in functions offered in
MLAB.  (See the MLAB Reference Manual.)  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. Graphics in MLAB
===================

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 OS X 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 TextEdit, 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
current working directory, then the path to the directory where the
file is located must be specified to MLAB, either in the filename, or
more generally, 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.  pwd will 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 scroll bar in the
MLAB terminal window with the mouse.

You can edit the dimer.do file with the text editor of your choice as
discussed above.

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 editor programs.

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

end of shortmlab.intelmac

