Plotter Documentation

Version: Light (beta 1.0)
Date:    4/14/99

Disclaimer
----------

Power Plot is freeware for the HP48 Graphing Calculator.  It is to be
distributed widely and freely.  Please note that this plotter is written in
system RPL and Saturn assembly language.  As is true with any ml/sysrpl
application, this plotter can potentially cause a warmstart or memory loss.
I am not responsible for any adverse effects that this plotter can potentially
cause.  If you encounter any problems, please email me immediately so that
someone else does not make the same mistake.  I will either fix the bug if I
have time, or add it to a list of known problems until I get the chance to fix
it.  The source code for this plotter is available upon request for private
use only.  If you want the [partly] commented source and development directory
or if you find a bug, please email me at awallace@utdallas.edu or ICQ me
(18236839).

Plotting Equations
------------------

Functions can be plotted directly from the stack in two ways.  The function(s)
can be in a list (multiple functions) or without a list (single function).
Here is the stack syntax:

1: 'eq'
PLOT

-OR-

1: {'eq1' 'eq2' ... 'eqn'}
PLOT


The Main Menu
-------------

The main menu includes the following options:

ZOOM     

Invokes the ZOOM prompt.  Both zoom factors initialize to nothing so you must
enter a number in for both.  Press the DROP key (<-) to backspace if needed.
Negative (-) numbers indicate ZOOM OUT and positive numbers indicate ZOOM IN.
Acceptable entries include real numbers (+/-) or simple expressions involving
only the following operators (+,-,/,*).  Press ENTER to exit the ZOOM GUI and
replot using the new zoom parameters or press ON (CANCEL) to cancel the ZOOM
GUI and return to the main menu.  Please note that when you zoom in/out, your
plot parameters will not change permanantly.  This means that all zoom factors
are with respect to the original window settings.

TRACE    

Invokes the trace function.  The cursor initializes to the center of the LCD
(whatever x coord that is).  The left/right directional arrows move the cursor
on pixel to the left/right.  The up/down directional arrows are used to scroll
through the equations if there are multiple equations.  The SPC key invokes
the "Jump to location" prompt.  You can enter a x-coord and it will "jump" to
that (x,f(x)) provided that the x-coord given is within the range (xmin <=
coord <= xmax).  If the x-coord is outside of the range, the f(x) value will
be displayed and you will be returned to the "jump to location" prompt again.
This prompt can be exited by pressing ON (CANCEL) or ENTER which will return
to the trace application.  One of the useful features included in this tracer
is the ability to scroll the viewable window up or down when you trace off the
viewable screen.  This feature is not unlimited, so there is a "top" and 
"bottom".  You can use the hotkey EVAL to find the root of a function.  This
root function has been rewritten to be anywhere from 2 to 10 times faster than
the built-in ROOT command.  For the root finder to work properly, you need to
place the cursor near the root you want to find.  Since this implementation
finding roots is based on Newtons method, it will not be able to accurately
find a root that lies at a local extrema.  It may also find the incorrect root
if the guess is not reasonable.

STACK    

Returns to the stack, but leaves the plotter HALTed until the CONT(inue) key
is pressed.  Failure to return to the plotter before ending the current plot
can have unpredictable effects.  It is strongly advised that you do NOT
Warmstart the calc or start any other major application while the plotter is
suspended.

OPTS
	
This invokes the options screen.  When you exit the options screen by pressing
ENTER, the equations will be re-graphed automatically.  If you exit by
pressing ON, the changes you have been made will be canceled and you will be
returned to the main menu.  Please note that if you have used the ZOOM, the
zoom factor will be nullified and you will see the region that you specified
in the options screen.  See "The Options Screen" for more details.

EXIT     

When you get tired of plotting or you want to plot something else.  ON 
(CANCEL) can also be used to exit the plotter.


The Options Screen
------------------

The parameters are stored in the hidden (null) directory so that they do not
clutter the HOME dir.  Anytime you lose you memory, your plot options will
return to the default settings.  The following options are available:

XMIN     

This is the smallest (left-most) x-coordinate to be plotted.  Default is -6.5.

XMAX 

This is the largest (right-most) x-coordinate to be plotted.  Default is 6.5.

YMIN     

This is the smallest (bottom-most) y-coordinate in the visible display.
Default is -3.2.

YMAX     

This is the largest (top-most) y-coordinate in the visible display. Default is
3.2.

STEP

This specifies the increment.  By putting a '1' here, you get "full 
precision".  Putting a '2' here will plot at "half precision" which means a
calculation will be made at every-other pixel.  Higher numbers mean faster
(but less accurate) graphs.  Any integer under 11 is valid.

CONNECT  

When checked, the plotted points will be connected with a line.

AUTOZOOM 

When checked, the plotter uses the built-in autozoom function to select the
plot window.


Hotkeys in the Main Menu
------------------------

MTH	 

Pressing the MTH key at the main menu will re-draw the graph(s) "on-the-fly"
with the opposite angle mode (deg/rad).

PRG

Pressing the PRG key at the main menu will toggle the  CONNECT flag.

CST	

Pressing the CST key at the main menu will toggle the AUTOSCALE flag.

NXT

Invokes the hotkeys reference screen.  If you memorize what this one key
does, you will have "on-the-fly" reference to the others.

UP

Pressing the up directional key at the main menu will display the current
domain.

LEFT

Pressing the left directional key at the main menu will shift the domain to
the left.

DOWN

Pressing the down directional key at the main menu will shift the domain to
the default [-6.5,6.5].

RIGHT

Pressing the right directional key at the main menu will shift the domain to
the right.

Commands
--------

PLOT

Starts plotting the equation(s) on the stack (in a list).

OPTS

Invokes the options screen.

FIXOPTS

If any of the options become corrupted for any reason (or if Power Plot is
behaving strangely) run this to set the options back to default.

->ASCL

Takes a real number (preferably 1 or 0) off the stack and sets the AUTOSCALE
flag accordingly.  Anything that is not a "1" is interpreted as a FALSE.

->CONNECT

Takes a real number (preferably 1 or 0) off the stack and sets the CONNECT
flag accordingly.  Anything that is not a "1" is interpreted as a FALSE.

->STEP

Takes a real number off the stack and sets the STEP to that value.  The number
must be between [1,10] to be valid.

->YMAX

Takes a real number off the stack and sets the YMAX to that value.  The number
must be greater than the value of YMIN to be valid.

->YMIN
	
Takes a real number off the stack and sets the YMIN to that value.  The number
must be less than the value of YMAX to be valid.

->XMAX

Takes a real number off the stack and sets the XMAX to that value.  The number
must be greater than the value of XMIN to be valid.

->XMIN

Takes a real number off the stack and sets the XMIN to that value.  The number
must be less than the value of XMAX to be valid.

Notes
-----

The way the equations are handled by the plotter allows you to include
constants in your equations.  If a variable is not defined in user memory,
it will be treated as the independent variable regardless of name (X, Y,
Z, etc.).  This means that if neither X or Y are defined, they will be
treated as the same  (independent) variable.
	
Power Plot will display discontinuities.  There are some conditions for
them to show up.  A discontinuity will be reflected in the graph if the
plotter uses that exact x value as a point to plot.  At default window
settings, that would be at every .1 from -6.5 to 6.5 (assuming full res).
	
Power Plot makes use of some of the user flags.  Not to worry, any flags
used will be restored to their original setting.  However, in the event
that the plotter does not exit properly, some flags may be changed.  
Specifically, the user flag number 1 is utilized when the plotter is running.

There is a program added to this beta called "FIXOPTS" which will repair
any errors in the options which are stored in the null directory.  Should
these options become corrupted for any reason, run "FIXOPTS" to reset all
options to the default value.
	
A final note.  Power Plot is in BETA.  There have been many bugs already found
and it is reasonable to expect there may be more.  Be cautious when using this
plotter and be sure that you have backed up your memory before hand.  I will
not be held responsible should anything happen to your memory.


Credits

Power Plot is written and maintained by Aaron Wallace.

Thanks to Peter Karp for helping test and debug Power Plot.

Thanks to Chris Wahlen for his contributions to this plotter.
