                      PLOT - Version 1.2                  June 25, 1990
                      ==================
 
  By:                 
  John Cordes                               
  Department of Physics
  Dalhousie University
  Halifax, N.S.
  Canada B3H 3J5
  Telephone: (902) 494-2313
  E-Mail: CORDES@AC.DAL.CA


        PLOT  Copyright John Cordes 1990.  PLOT is freely distributable
provided this document is distributed with the executable file PLOT.PRG.

              *********  STANDARD  DISCLAIMER  ******************
  No guarantees, written or implied are made as to the suitability of this
program for any particular purpose. Anyone who uses it does so at their own
risk.

  Reports of problems, bugs or suggestions are welcome.

        *************************************************************

                     Brief  Description of PLOT:
                     ---------------------------

  PLOT is a two-dimensional plotting program for the Atari ST which runs in
high or medium resolution.  It's main features are (1) that it can plot a
large variety of functions entered at the keyboard, (2) it can plot data read
from disk files or entered 'by hand' in a built-in data editor, and (3) it can
produce good quality hardcopy on a variety of printers using GDOS printer
drivers and fonts.  PLOT was developed in GFA Basic, Version 3; it is based on
an earlier program I wrote in True Basic.

  Any number of curves, in various line and marker styles, may be overlaid on
a single plot; any combination of individual curves may be saved for printer
output. 

  Brief, context sensitive, on-screen help is available at many stages of the
program at the touch of the <Help> key.  Some, but not all, of the information
in the help screens will be repeated below; the user is urged to read carefully
the information in the help screens themselves. 

 =================  A More Detailed Description of PLOT  ===================

                        1. Editing Keyboard Entry  

   When you are being prompted for entry of a numeric variable or a function
the normal editing features are (usually) available: <Esc> to clear the field,
Delete, Backspace and Arrow keys all work; in addition <Home> takes you to the
beginning of the input string and <Control-Home> takes you to the end.
However, the Home keys do not work if you are entering values in the dialogue
boxes on the alternate (GEM menu) screen.

                        2. The  Plotting  Box 

  This program doesn't go in for automatic scaling!  The user is always
prompted at the beginning of plot construction for the range of the plotting
box (i.e.  xlower, xupper, ylower, yupper) and tick/label spacings, etc.  The
actual *size* and *location* on screen of the plotting box can be set from an
alternate screen with a GEM menu bar (the box coordinates are described in the
next paragraph); also the presence/absence of the outer frame can be toggled
from the menu bar.

  If you wish to change the default settings of the size and location of the
plotting box on the screen, you should be aware that the coordinates used are
pixels, measured relative to the upper left hand corner of the screen.  For
the high resolution screen the range is 0 to 639 pixels horizontally and 0 to
399 pixels vertically.  For the medium resolution screen the range is 0 to 639
horizontally and 0 to 199 vertically. 

  A brief rundown on the variables you will be prompted for in setting up the
plotting box (just hit return at the prompts to accept the defaults):

 xlower: x-coordinate of left edge of plotting box

 xupper: x-coordinate of right edge of plotting box

 xtick: spacing of the minor tick marks. If set to zero the x-axis will be
         omitted entirely.  If xtick < 0, there will be no major or minor
         ticks on the x-axis but there will still be ticks on the surrounding
         frame (which I refer to as the plotting box).

 xlabel: spacing of the major tick marks.  The labels will be placed at the
         major ticks if xlabel > 0.  If xlabel = 0 there will be no major ticks
         or labels anywhere.  If xlabel < 0 there will be no labels but major
         ticks will occur at spacing ABS(xlabel).

      ***********   Summary of various tick/label settings  ***********

   1. xtick>0,xlabel>0: Standard case. Minor ticks at xtick; major ticks and
                        labels at xlabel.
   2. xtick=0,xlabel>0: Omit x-axis. Major ticks and labels on box.
   3. xtick<0,xlabel>0: Omits x-axis ticks. Major/minor ticks/labels on box.
   4. xtick>0,xlabel=0: No labels. Only (minor) ticks at xtick.
   5. xtick=0,xlabel=0: No x-axis, no ticks, no labels.
   6. xtick<0,xlabel=0: No x-axis ticks. Minor ticks on box; no labels.
   7. xtick>0,xlabel<0: Omits labels; still have x-axis major/minor ticks.
   8. xtick=0,xlabel<0: Omit x-axis. Major ticks on box, no labels.
   9. xtick<0,xlabel<0: No x-axis ticks. Major/minor ticks on box; no labels.

   Of course, if the plot box (i.e.  the outer frame) is not being drawn (it
can be toggled on/off in the alternate screen) some of the above statements
must be modified in a reasonably obvious way.

   ********************************************************************
 ylower/yupper: Similar to xlower/xupper (see above). 
 ytick/ylabel: Similar to xtick/xlabel (see above).

 grain: This parameter determines the number of function evaluations, i.e. the
        fineness of the 'mesh'. The recommended range is (4..2000), but the
        actual lower limit is 1, while the upper limit is constrained by the
        available memory in your machine, at least for screen plotting. I have
        tried grain = 10000 with no problem. However, saving a curve for
        printer output is another matter. At the moment there is a hard coded
        constraint of a little less than 10000 for the total number of function 
        values which can be saved for later GDOS printing; if there are
        arrays involved the x-coordinates need to be stored as well.

 line style/thickness: The best way to find out about the line styles
	available is to run the program and use the Help key to read help
	screen number 3.  If a positive line style is chosen there will be a
	further prompt for a line thickness.  This should be an odd number in
	the range 1..35.  No harm is done by entering an even number but you
	won't get it!  Also, if the line thickness chosen is anything greater
	than one, the style reverts to the simple solid line (style 1).
	Therefore, to get one of the styles 2..6 you must enter 1 for the line
	thickness.

          The negative line styles are used to access the individual point
	plotting mode.  E.g.  entering line style -8 (negative 8) results in a
	small solid box being plotted at each of the mesh points; no
	connecting line is drawn in this case.  See help screen 3 for
	descriptions of the other 7 point styles.


                      3.  Function Plotting 

  In addition to the standard arithmetic operators +, -, *, /, ^, the
following functions of the single variable x are supported: SIN, COS, TAN,
ASIN, ACOS, ATN, EXP, LOG, SQR, SINH, COSH, ABS, SGN, HVS (Heaviside step
function).  In addition, two kinds of Bessel functions are supported at
present: BSJ(n,x) - the Bessel function of the first kind (usually called
J(n,x)) and BSI(n,x) - the modified Bessel function I(n,x).  The Bessel
functions are only available for integer order n; in fact you must use an
integer CONSTANT, so that, e.g.  2*3 is not acceptable for n, but 6 is.
HVS(x) is defined to be equal to 1 for x >= 0 and to be 0 for x < 0.  [See
also below for the INTEGRATE command].  The function parser is not case
sensitive - the function names are shown in upper case in this document simply
for easy visibility.

  Some effort is made to trap singular behaviour so that, for example, the
function 1/x can be plotted in a solid line style over a region spanning the
origin.  Some mathematical liberties are taken in the process, so that, for
example, if a plot of SQR(x) is requested in the range -5 < x < 5, the plot is
given properly for positive x but nothing is shown in the region where x is
negative and the square root doesn't exist (in the domain of real numbers).
The lesson here is that in certain cases the apparent plotting of a zero value
should not necessarily be taken to mean that the function is actually zero
there!  In addition you should be warned that if you try taking a *function*
of SQR(x) (such as SIN(SQR(x)) or BSJ(1,SQR(x)), say ), with negative values
of x being required in the plotting range, a fatal error may well occur; the
program will quite likely quit abruptly and ungracefully exit back to the
desktop (or shell or whatever).  Sorry about that.

  Some examples of functions which could be entered at the (k)eyboard prompt
are:

SIN(3.1*x/4)          -  Ordinary trigonometric function
BSJ(1,x^2)            -  Bessel function J(1,x^2)
.5*HVS(3+x)*HVS(3-x)  -  Draws a sort of 'top hat' function in range (-3,3)


                       4.  Integration

  An additional possibility in function plotting mode is to plot the integral
of a function, from a specified lower limit to the variable upper limit x.
The syntax for this is to enter INTEGRATE(f(x),a) where f(x) can be composed
of the functions listed above and 'a' is the lower limit of the integral.  The
parser is not case sensitive and for the case of the integration function,
only the first five letters are required.  So for example

INTEG(.5*BSJ(1,x),0) - Integrates (1/2) times the Bessel function J(1,x),
                        with lower limit of integration 0.
       
         x
        /
  i.e.  | dx  0.5 * J(1,x)     will be plotted as a function of x.
        /                                                      
        0

 Apart from the integrand f(x), no other function (not even a constant) may
appear in the Integrate command;  i.e.  the following is *NOT* allowed:

  .5*INTEG(BSJ(1,x),0) <--- ILLEGAL !  That is why the factor of .5 was
included in the integrand in the previous example.  

   HINT: If a syntax error is reported (e.g.  missing parenthesis or Bessel
function index not an integer constant) when entering a function, and you have
trouble getting rid of the error message no matter how you edit your function,
try exiting function entry mode (use ESC to clear the edit line and enter a
backslash '\'), then go into (k)eyboard mode and try again.

                    5.  Coordinate  Mode

  When the function has been plotted the console bell will sound and you will
see a notice on the screen to the effect that pressing <Esc> will take you
into coordinate mode.  If you accept this invitation the mouse cursor will
become a crosshair with which you can read off the (x,y) coordinates of any
point on the screen.  This feature is especially handy for finding zeros of
functions, or the x-value at which two curves cross.  Exit with another <Esc>.
If you exit (or bypass) coordinate mode without meaning to you can always plot
a 'dummy' curve, say y=0 or y=1e9, then you get another chance to enter
coordinate mode.  If you do not want to enter coordinate mode, just touch
another key, such as the space bar.  At this point there are four possible
commands which will be accepted by PLOT:

                       6. After Coordinate Mode

 (a).  Pressing <Help> results in a message at the bottom of the screen which
says to press <G> for the GEM menu bar screen (referred to throughout this
document as the 'ALTERNATE' screen), where other parameters can be set and
other functions performed, or to press <L> for entering 'legends' on the plot
(see item (c) below).

  (b).  Pressing <F1> takes you directly to the 'alternate screen'.  This is a
screen with a standard drop-down menu bar, from which various parameters may
be set.  Access to desk accessories is also available here.  Under File there
are options to save a plot as an uncompressed Degas file (.PI3 or .PI2,
depending on the resolution), or to run an external program. The printer
device number can also be altered from the default in this screen.

  (c).  Pressing <L> enters legend mode.  You will be prompted to enter some
text.  When done press <Return> and you will be asked whether the legend, or
floating label, should be horizontal or vertical.  After answering that query,
you can move the legend around the screen with the mouse - click with the left
button to 'deposit' the text on the screen at the desired places.  When you
have finished clicking press <Esc> to 'paste' down your choices, or <Undo> to
remove all the legends just deposited.  You can press <L> again to add further
legends or proceed to step (d).

  (d).  Pressing <S> is essentially a 'continue' command: you will be asked
whether you want to save this curve for printing; assume for now that you
answer no.  You will then be asked if you want to change the plot parameters
(if this is the first curve in the plot) or if you want to plot any more
curves (if this is not the first curve or if you have finished trying new
settings for the plot parameters (such things as xlower, grain, style, etc.).

                          7.  Array  Plotting

  Choosing option (a) for array plotting presents the user with a further
choice: reading a data file off disk (f) or using the simple built-in data
editor (e).  If this is the first curve, the plotting box parameters will next
be prompted for.  Then, either (option (f)) a file selector box will appear
(default extender ".ASC") for choosing a data file, or option (e) lands you in
the data editor.

  If a data file is read in you will be told the number of points read and
then given the option of looking at or modifying the data in the editor,
transforming the data in various ways, or plotting the data either 'as is' or
with fitted curves (a linear fit, a polynomial fit (more about this later), a
fast cubic spline which passes through all the data points, or a smoother (but
MUCH slower) spline fit which doesn't necessarily pass through the data
points.  For this latter option (ArrayOp 4) the spline order may be input -
the allowed values are 1, 2, or 3 (e.g.  this last would mean the spline is
with cubic curves).  More details on these options may be found below.

           =============  Data  Files  ====================

  The format of the data files required is illustrated in the following
examples:

; comment1: this data file might be output from a Fortran program, say.
; comment2
.
.
; commentN
.27 3.4
1e-11 4e12
0 0
11 -.1

  Any number of comment lines may occur at the BEGINNING of the file.  The
first character on a comment line must be a semi-colon <;> .  After this come
the x-y coordinate pairs.  The separators may be spaces (any number) or a
comma; the separator type should not be mixed in a single file, however; i.e.
don't use commas for some coordinate pairs and spaces only for other pairs.
The following is ok, though:

.27, 3.4
1,2
 -2.5,  7
 
  i.e. when a comma is (consistently) used as the separator there may also be
leading/trailing spaces on the x and y values.

                     Summary of Array Options:
                     =========================

 ArrayOp 0: Plots the data points 'as is'.  This allows for using individual
	   markers for the data points (use a negative line style) or drawing
	   a continuous curve through the points (as in function plotting).

 ArrayOp 1: Linear fit - a simple least squares straight line fit.  The
	   slope(m) and intercept(b) are shown on the screen with the fitted
	   line.  There is no way to recover these values once this screen has
	   been left.  At the moment this option is somewhat superfluous since
	   option 2 (see below) can be used with degree set to 1.

 ArrayOp 2: Polynomial fit - the user is prompted for the degree of the
	   polynomial to be used (this is the exponent of the highest power of
	   x in the polynomial).  E.g.  a(1)+a(2)*x+a(3)*x^2 has degree 2, and
	   3 coefficients to be determined, so at least 3 data points are
	   required.  If you enter a degree which is greater than one less
	   than the number of data points the program sets degree=Ndatapoints
	   -1.  The fitting is done by a singular value decomposition of the
	   'design' matrix, rather than directly solving the so-called normal
	   equations.  This SVD technique is slower (and takes a lot more
	   code) than using the normal equations but is much more informative
	   and reliable (see, e.g.  Numerical Recipes, by Press, Flannery,
	   Teukolsky and Vetterling, p.518 in the Fortran volume).  After
	   entering the desired degree for the fitting polynomial you will be
	   asked for the range of x - values over which the polynomial should
	   be drawn (you may only want the fitted curve to be shown in the
	   neighbourhood of the data points rather than over whole range of
	   the plotting box).  Then the curve will be plotted.

                  Viewing the Fitting Parameters and Singular Values
                  --------------------------------------------------

               After finishing with the coordinate display mode and pressing
	   <S> to move on, you will be asked if you want to see the results of
	   the fitting routine.  Here you see not only the polynomial
	   coefficients but also the singular values of the design matrix.
	   Some of these may have been set to zero by the program because they
	   fall below the limit set by the relative error tolerance.  PLOT
	   uses a default tolerance of 1.0E-06; this may be modified while you
	   are on the fitting parameters screen by pressing <Control-T>.  (The
	   new value will stay in effect until the present series of plots is
	   completed unless of course the value is edited again.) When you
	   leave the parameters screen the fitting parameters and the
	   coefficients are lost, so write them down if you need them!

               The next query is whether anything more is to be done with the
	   data?  Answer yes if you want to plot the individual points (Option
	   0), try a different fitting routine, use the data editor, etc.

  ArrayOp 3: This is a fast cubic spline interpolation through all the data
	   points.  PLOT will prompt for xmin and xmax values for drawing the
	   resulting curve.

  ArrayOp 4: This is a slow spline fit (not just interpolation) to the data.
	   It is so slow that it is probably impractical for data sets with
	   more than about 15 - 20 points, say (unless you are very patient!).
	   The order of the spline is input by the user; 3 is a cubic spline
	   (but *not* the same as option 3 - try it out and see).

            *********************************************************

                            8.  Printing

  Good quality hard copy is possible if GDOS is present in the machine and a
suitable printer driver plus font files are available on disk.  The default
device number for the printer driver is 23 for the monochrome mode and 21 for
the medium resolution (these numbers just happen to match my own setup) - this
can be altered with a drop down menu selection in the alternate screen; if you
*are* going to alter the device number I strongly recommend that you do it
when starting up PLOT, before you forget (the voice of experience
speaking...).  Here also the font used for the axis labels and any additional
floating labels/legends may be chosen.  For now this is only set up to handle
the Swiss or Dutch faces; the default is Swiss.  The user interface here
leaves something to be desired: it would be nicer (except for the memory
demands) to also be using the associated screen fonts and also to enable
switching between different fonts and point sizes for different legends.
Someday...  The program has been tested with the 9-pin driver FX80.SYS (on a
Citizen 120D), the 24-pin driver LQ800.SYS (on a Star NX-2400 and an Epson
LQ800) and the Atari laser printer driver SLM804.SYS (on, of course, an
SLM804).

  If GDOS is present (it must have been loaded at boot time by being in an
AUTO folder), you will be prompted at a suitable stage to see if a given curve
should be saved for printing.  I will elaborate a little more on this: You can
overlay as many curves as you please in a single plot, and any or all curves
can be tagged for plotting.  This means that the selected curves, together
with any floating labels/legends which you may have added to the plot via the
<L> key, will be printed on a single plot, after you have declared that no
more curves are to be added to the plot.

  You can also save the plot to a file GEMFILE.GEM by 'printing' with device
number set to 31 (metafile) - the ASSIGN.SYS file must contain the metafile
driver META.SYS for this to work.  This file can then be printed with
Migraph's OUTPRINT.PRG; I don't particularly recommend trying to do much with
the file in EASYDRAW itself, you'll find it's pretty 'messy'.  Unfortunately,
I haven't yet figured out how to get the text/labels printed from the metafile
(the text seems to be there, but I can't find the right magic to get it
printed in the metafile mode -- I'm still learning how to get along with
GDOS).

  [If GDOS is NOT present the only reasonable prospects for hardcopy are
either saving as a Degas picture or doing a screendump with Alt-Help;
SNAPSHOT.ACC doesn't get along well with PLOT at all.]

  At the time when a curve is first selected for printing, PLOT will go to
disk and look for the printer driver according to the device number chosen
(defaults: 23 (monochrome), 21 (colour)).  This number should match the number
given to the printer driver in the ASSIGN.SYS file.  If the driver is found
PLOT will offer some default scaling factors for both the horizontal and
vertical directions, appropriate to the resolution of the device to which you
are planning to send the output.  These typically result in a printed plot of
about 5.5" (horizontal) by 4.5" (vertical) on a 24-pin printer and about 4.25"
by 3.25" on a 9-pin printer; this assumes that you have not altered the
default plotting box size for the on-screen display.  Your results may vary,
however; do some experimenting with the scale factors!  For now, as mentioned
previously, only one font face/size can be used for all the text output (this
includes the axis labels) in a given plot.  The printouts look much better on
the 24-pin printers (using Migraph's printer drivers) than on the 9-pin -- at
least, that's been my experience.  Only the built-in system fonts are used for
the on-screen display.

           =============  ASSIGN.SYS files ================

 I usually use the same ASSIGN.SYS file used by EASYDRAW, but since PLOT
doesn't use screen fonts you can save memory by eliminating these.  A
reasonably minimal ASSIGN.SYS file suitable for PLOT, is shown below.
Un-comment (by deleting the semi-colons) some/all of the fonts in the FX80.SYS
(Epson 9-pin driver) section for use on an Epson compatible 9-pin printer.
The actual printer driver and font files must be available on disk in the
location shown in the PATH variable (in the ASSIGN.SYS example file below the
fonts and driver would be in folder GEMSYS on drive A:).

PATH = A:\GEMSYS\
; Change A: to drive with \GEMSYS\ folder
00p screen.sys
; --START OF SCREEN FONTS--
01p screen.sys
02p screen.sys
03p screen.sys  ; PLOT doesn't use GDOS screen fonts
04p screen.sys  ;   "     "     "   "      "     "
; -- START OF PRINTER FONTS --
21 FX80.SYS     ; Epson 9-pin and compatibles printer driver
; SWISS (Sans Serif) 9-pin printer fonts
;EPSHSS07.FNT
;ATSS10EP.FNT
;ATSS12EP.FNT
;EPSHSS14.FNT
;ATSS18EP.FNT 
;ATSS24EP.FNT
;EPSHSS28.FNT
;EPSHSS36.FNT
23 LQ800.SYS   ; Epson 24-pin and compatibles printer driver
; SWISS  24-pin printer fonts
P24MSS07.FNT
ATSS10SP.FNT
ATSS12SP.FNT
ATSS18SP.FNT   ; this is the default font used by PLOT in mono mode.
ATSS24SP.FNT
P24MSS36.FNT
; METAFILE
31r META.SYS

                             Memory
                             ------

  Memory is a problem in using GDOS and its associated drivers and fonts.
When PLOT is first run it displays the free memory remaining - this figure
must be at least around 330K for the 9-pin or 24-pin drivers to work.  If
you're close to the limit you may only get 1 set of fonts loaded; also I'm not
sure what happens if the memory is very tight and you try to save several
curves for printing on the same plot - one or two curves should be alright.
In my tests with the SLM804 I was using a Mega-4 and allocated over 3
Megabytes for the GDOS stuff (combination of the large printer resolution and
many fonts in the ASSIGN.SYS file).  1.3 Megabytes or so would probably be
sufficient for the SLM804 if you don't need to load a lot of fonts (not much
use in the present version of PLOT anyway!).  It would be probably be possible
to do some fine tuning and reduce somewhat the memory requirememt for the
9-pin printing but I haven't explored that avenue as yet.  I get along fine
with my normal setup of a 1040 ST and the LQ800 driver for my Star NX-2400;
the program has also been (less extensively) tested (with 1040's) on a 9-pin
Citizen 120D and on an Epson LQ800.  I have tried to put in a fair amount of
intelligent error trapping in case insufficient memory is found, but it's
always possible you could have a crash.
