Mega CD-ROM 1/megacd_rom_1.zip/megacd_rom_1/PLOT/FCNPLT41.ZIP/README.DOC

Text File | 1990-11-05 | 23KB | 414 lines

Function Plotter version 4.10 documentation.  THIS PROGRAM IS SHAREWARE.
Please support our efforts, registration is $20.

To start function plotter for the first time type "fcnplt x", where x is:
h  -for hercules
c  -for cga
e  -for ega or vga (with color monitor)

If after running the program, you create a configuration file, type
"fcnplt" (no parameters). Function plotter will then use the
configuration file with your custom configuration.  If you want the
configuration file in the root directory simply put it there and type
"fcnplt r". Function plotter will then look in the root directory for the
configuration file.

files:  fcnplt.exe......The main program.
        hercules.exe ...Hercules driver.  This file is needed to print
                        from a hercules compatible display.
        ega.exe ........EGA driver.  This file is needed to print from an
                        EGA compatible display.
        func.fcn........Sample function file for demonstration.
        data.dat........Sample data file for demonstration.
        readme.doc......This documentation.

SHAREWARE

If you find this program useful, please register. Your support is vital
and has a number of benefits. You will be put on the mailing list for
future upgrades. They will be mailed to you for a nominal fee or for free
if you send a stamped, self-addressed mailer and disk. Your questions,
submitted in writing will be answered. A printed manual will be available
in the future and will only be offered to registered users. Please send
your registration fee of $20 to: (also questions, comments)

Robert G. Kaires
609 Glover Dr.
Runnemede, NJ  08078

ENHANCEMENTS IN FCNPLT 4.1 FROM FCNPLT 4.0

1) Polar functions can now be evaluated.
2) Symbols, line styles, number of points, data file names, are now
   unique to each stack position.
3) Using F10 now solicits verification before exiting.
4) The position of the cursor is now maintained in each editing position.
5) When reading data from an external file, column information is
   retained (appended to the data file name).

USES

1) Quickly reviewing data in a linear or log format. Data is in column
   format and can have up to 9 columns. You can plot any column vs. any
   other column.
2) Entering function strings and converting to data.  This data can then
   be plotted or read out to a data file. Functions can be linear (y =
   y(x)) or polar (r = r(theta)).
3) Use it as an educational tool.  Examine Taylor series, Fourier series
   and Chebyshev series approximations.  Look for roots of polynomials.
   Look at functional behavior as you vary parameters.
4) Reading very dense data files and then examining detail using
   "exploded" views.
5) Use the calc mode as an intelligent formula calculator.

OVERVIEW

This program plots rectangular or polar functions entered from the
keyboard. The functions can also be read in from an external file and
placed on the line being edited. This program can convert the function to
data and then write the data to an external file. Data from an external
file, which can have many columns, can be read in and plotted in the
format of any column verses any other column. Multiple sets of data can
exit simultaneously in memory in a data "stack". This allows one to
quickly overlay data, to experiment with different formats, without
having to constantly read in or generate new data. Data can be plotted in
a linear or logarithmic fashion. The actual data values can be examined
point by point (alt v) using the cursor keys. When using this alt v
feature on a log-log plot, slopes can be quickly determined since the log
of the value is displayed. Other features include, windowing of data with
cursor or mouse, control of tic marks, grid control, autoscaling of data,
custom configuration file, and more. The configuration file can be edited
(very carefully) to allow any number of data points (default is 500) and
any number of stack positions (default is 5). Of course there are memory
limitations. More  on this later.

SUPPORT

This program supports Hercules, CGA and EGA. Hercules and CGA have been
tested. EGA has been tested on an EGA and VGA color monitor. I have not
tested ega mode on a monochrome monitor. Printer drivers are supplied for
Hercules and EGA, for use with DOT MATRIX printers. Those using a CGA
monitor should load the memory resident program, graphics.com, first, and
then use PrtSc to get a printout. Hercules and EGA users, make sure the
file hercules.exe or ega.exe is on your disk. When using these drivers,
use a margin of "0" if your printer doesn't support "esc l" (see your
printer manual).

QUICK INTRODUCTION

When function plotter starts, the cursor is located in the position
reserved for function "strings".  Simply type in a valid function of x
(eg. type sin(x), not y=sin(x)). For polar functions see below. If you
press the "Enter" or the tab key at this point, the cursor will advance
to the next editing position, which is the number of points (the back tab
key will move the cursor to the previous editing position).

If you need to see the valid function names while editing the function
string, press the F1 key. This can be done even in the middle of typing a
string. The string will not be lost.

Functions can have "x","y" and "z" as variables (or no variables); "x" is
the horizontal plotting variable; "y" and "z" are really constants that
are solicited when you "update" the function (generate data). The "ymin"
and "ymax" on the second line refer to the minimum and maximum vertical
(data) values and have no relation to "y" in functions.

Now assuming you have a function, move the cursor to the "points"
position (press tab or Enter). This is the number of data points to be
generated for the  function (when you press F2). Enter a number from 2 to
500. The next four editing positions are the minimums and maximums for
the x (horizontal)  and y (vertical) axis.  Pay particular attention to
the x axis limits, the data will be generated between these limits for
rectangular functions. The y axis limits are less important, the data is
not truncated at these limits, the plot simply is. You can always use the
F8 key to bring the full y values on scale, after the data has been
generated.  Now press the F2 key. This generates data points for the
function between the x limits you set. Now you have data. You should
understand, however, that typing in a new function at this point could be
confusing. The data doesn't "update" to represent the new function UNTIL
you press the F2 key again (or Alt F2 for polar functions). Now, just for
practice, put the cursor in the "fcn" (first) or "points" (second)
position. Now press the down arrow key (make sure num lock is off). You
are now at stack position 2. Enter a function, set limits, and press F2.
Now you have new data.  The old data is not lost!  Just position the
cursor in the "fcn" or "points" position again and press the up arrow
key, the old function and data are still there. Now you can overlay the
plots if you like (the scales should be the same for this to make sense).
Be careful if you change the number of points. If the data has 100 points
for instance and you change "points" to 50, only the first 50 points will
plot. On the other hand, if you change "points" to 200, the last 100
points (which don't exits) will be plotted at 0,0.  No real harm done.
Each function in each stack position as a unique "points" value and a
unique plotting style and symbol. This is an improvement over the last
version. Confusion can result if you changed the x or y limits for two
functions (or they were changed "for you" with the autoscale feature).
Your data may be off screen or not scaled correctly. Be aware, if you
press F8 the y axis will scale TO WITHIN THE X AXIS LIMITS (not
necessarily the full x range). If you press F9, the x AND y axis will
autoscale and all you data will be visible.

When function plotter first starts, you will see "fcn(fcn)[ 1]:" on the
first line of the editing window. The number in square brackets indicates
the stack position. The "fcn" in parenthesis indicates that a function
(or null function) but NOT data exits in this stack position. The
parenthesis can also contain the words "dat" or "pol". If data is
generated from a function using the F2 key or data is read in from an
external file, "dat" will appear in the parenthesis. If polar data is
generated from a function using the alt F2 key, "pol" will appear in the
parenthesis instead of "dat". If data is read in from an external file
"dat" will appear, no matter how the data was generated.

To summarize the last paragraph: "fcn" in parenthesis indicates that no
data is in this stack position, "dat" in parenthesis indicates that
rectangular data has been generated from a function OR that external
data has been read in, and "pol" in parenthesis indicates that polar
data has been generated from a function string.

POLAR FUNCTIONS

The only variables allowed in functions are x, y, and z. For
rectangular functions, the variable x is considered a linear variable.
For polar functions x is an angular variable (in radians). In either
case the variables y and z are constants that are solicited when you
update a function (using the F2 key for rectangular or Alt F2 for
polar). Function plotter does not "know" (or care!) whether a function
is rectangular or polar until you "update" by pressing the F2 key or
the Alt F2 key. If you press F2, the function is treated as
rectangular whereas is you press Alt F2, the function is treated as
polar. Try a simple function. Enter the function "1", now press F2 and
plot the function. Now press Alt F2. Function plotter now asks, "Polar
fcn: enter angles x1,x2 [0,6.28319]?". It is asking for the angular
range of the angular variable x. Hit Enter and the default 0 to 2 pi
will be used (remember angles are always in radians). Now plot the
function. In the first case the function is y=1 and a horizontal
straight line is plotted. In the second case the function is r=1 and a
circle is plotted (looks like an ellipse unless your aspect ratio is
just right). Did you notice that when you pressed Alt F2, the
"updating function" message appeared twice? Function plotter is
converting the polar function to rectangular data by calculating
r*cos(x) for the abscissa and r*sin(x) for the ordinate. Try the
following polar functions:

  circle:              c

  ellipse:             1/sqr( (cos(x)^2 / a^2) + (sin(x)^2 / b^2) ),

  cardioid:            a * ( 1-cos(x) )

  hyperbolic spiral:   a/x

In the above polar functions a,b, and c are positive constants.

CONTROL AND ALT KEYS

Certain control and Alt key combinations are "active". These control the
third line options among other things. For a list of active control and
Alt keys in function plotter press Alt h (help). Note that on the third
line, certain letters are capitalized, these  correspond to the Alt or
Ctrl keys which activate those items.

The following list describes the control and Alt keys.  The first 4
control keys can be used only when the cursor is in the function editing
position.

Alt f  : Gets a function from an external file.
Ctrl f : Puts the function (string) into an external file.  The file is
         created if it doesn't exist or appended to if it does.
Alt d  : Gets data from an external file.  If "auto" is on (use Alt a to
         turn it on), the x and y axis is autoscaled as the data is read
         in.  "Points" are set to the number of data points read.
         X axis data is assumed to be in "xcol" (change with Alt x, see
         below).  Y axis data is assumed to be in "ycol" (change with
         Alt y, see below).
Ctrl d : Puts the data, that was generated from your function, into an
         external file.
-------------------------------------------------------------------------
Alt e  : Toggles the "erase" flag.  When on, the plotting area is erased
         before plotting.
Alt a  : Toggles the "Autoscale" flag.  When on, the y axis is autoscaled
         before plotting.  Autoscale cannot scale a constant function
         (eg. 1.5); ymin will equal ymax.  If you try to plot this you
         will get an error message.
Alt t  : Toggles "extended functions".  These are additional functions
         which are defined using the "intrinsic" (more elementary)
         functions.  They can be turned off for faster "compilation".
Alt g  : Toggles the grid.
Alt l  : Toggles linear/log scaling.  This toggles in a binary fashion.
         Try it to see what I mean!
Alt x  : Changes "xcol", which is the column for x axis data that is
         used when you read in data from an external file.
Ctrl x : Changes the number of divisions of the x axis.
Alt y  : Changes "ycol", the column for the y axis data.
Ctrl y : Changes the number of divisions of the y axis.
Alt c  : Get a screen value with cursor or mouse (will use mouse if
         connected).
Alt m  : Get a screen value with mouse. This is a little easier to use
         for those of you with mice.
Alt v  : Gets values on the function using the cursor keypad.  Using the
         left/right arrow keys moves you along the function or data.  The
         x and y values are displayed as you move along.  CAUTION: a
         cursor will be displayed on the plotted points starting in the
         middle of the data set.  If points are plotted off scale you may
         not see this cursor!  You can use the up/down cursor to change
         the size of the cursor.  Also use the tab, home, and end keys.
Alt S  : Changes the plotting symbol and toggles a connecting line.
Alt h  : Prints the control and Alt key menu.
Alt w  : Windows the data using the cursor keypad or a mouse if one is
         installed.  Use F3 to plot the data after using alt w.  Use F9
         to effectively "un-window" the data.
Alt z  : Saves the setup in a configuration file called fcnplt.cfg.
         Warning: 24 different parameters are saved (see below), if you
         only want to change one parameter it is suggested that you exit
         the program, then restart, change the one parameter, and then
         save.


The configuration file is a normal text file and can be edited. This
should be done very carefully. No error checking is done as the file is
read in on startup.  Since alt z is the usual way to write to the file,
this is not normally a problem.  There are two parameters that can be
changed ONLY by editing the configuration file however.  These are 1) the
maximum number of data points and 2) the number of stack positions.  The
defaults are 500 and 5 respectively.  Subject to memory limitations, you
can set these numbers to anything you desire.  Once again, be careful
editing this file.  If the program crashes unexplainably, and you have
edited the configuration file, delete the file fcnplt.cfg, and start
over.  Just use Ctrl z from inside the program to create a new
fcnplt.cfg.  The following is an example configuration file:

hercules,data.dat,func.fcn,circle
1234,100,7,-6.28319,6.28319,-1.1,1.1
on,off,on,off,off,off,on,on
1,2,10,10,.5

line 1: display card, default data file name, default function file name,
default symbol (valid symbols are: none, circle, square, dot)
line 2: MAXIMUM NUMBER OF DATA POINTS, default number of data points,
NUMBER OF STACK LOCATIONS, xmin, xmax, ymin, ymax
line 3: automatic erase before plot, autoscale, extended functions, xlog,
ylog, grid, connecting line (for plotted points), symbol fill
line 4: x column, y column (to use when reading in external data), number
of divisions of x axis, number of divisions of y axis, symbol size

The capitalization in line 2 indicates the items you can't change in the
program (using alt z).  In the example configuration file, the maximum
number of data points is 1234, and the number of stack locations is 7. It
is suggested that only these two items be changed by editing this file.

MISCELLANEOUS

While editing you are always in insert mode.  Pressing the control
PgDn key deletes the entire entry.  The following keys are useful:
del, backspace/del, home, end.  When editing the function or number of
points the "up arrow" and "down arrow" keys chance stack position.
These keys do nothing if you are in any other editing position (ex.
you are editing xmin).

While reading functions from an external file, up arrow, down arrow, home
and end keys are active.  These keys change the line you are viewing.
Simply press return to read in the function on the line you are viewing.
In the sample file "func.fcn", I have included comments on some lines.
The comment precedes the function.  Don't read in the comment.  If you do
no harm is really done, you just can't process it.  Use Ctrl PgDn to
delete the line and use alt f again, to read the function file again.

When in the cursor mode (alt c), window mode (alt w) or mouse mode (alt
m, with no mouse) the following keys are active: tabs, PgUp, PgDn, home,
end.  Also right, left, up, and down arrows.

While editing xmin,xmax,ymin,ymax  you can enter numeric expressions such
as pi + cos(.5) + (.5)^3 , just like you would in the calculator mode.
You cannot use the "extended" functions here. For instance you cannot use
cosh(3) for xmin even if extended functions are active. You can however,
use cosh(3) in the calculator if extended functions are active.

Extended functions, of course, can be plotted and their values "picked
off" with the cursor (alt v). They are called extended because I process
them so that they are transformed to the "intrinsic" functions. eg.
cosh(x) is transformed to .5(exp(x)+exp(-x)). They can be used
recursively. eg. cosh(cosh(x)) or cosh(exp(sinh(x))) etc. They can be
turned off. Why? Because eventually they may consume an inordinate amount
of time (when I add more functions). Currently, when you type a
functional expression, if it does not compute (so to speak), additional
processing is done to see if it contains my so called external functions.
This happens even when you type a mistake, such as "cos(x))". Currently
the delay is very slight.

Floating point exceptions (overflow and underflow) are handled by setting
the value there equal to zero (plot tan(x) to see how this affects your
plots). If anyone has a better idea, let me know.

Data files (for reading) must be in column format with at least one
space separating data items. Any column can be plotted verses any
other column (by changing xcol and ycol with alt x and alt y).  When
you generate data from a function and write it out to a file there are
only two columns. You can, however, read in data which was generated
with another program containing more than two columns.

When using the "d" option to get a directory listing, the program
"shells" out to DOS and does a "dir/p".  After the directory is listed
you must hit ENTER, even though you are not specifically asked to do so,
in order to return to the program.

The program is not case sensitive (as far as I know), except in one small
area. When you are in the calculator mode and you are entering x,y or z
values for a function, you must use lower case q to quit.

EXAMPLES

WRITING FUNCTIONAL DATA TO DISK:
Enter a function, set all limits and use F2 to generate data. Then type
Ctrl d and enter a file name.

READING EXTERNAL DATA FROM DISK:
Hit up arrow or down arrow if you want to get to an unused stack
position. Press Alt d and enter a file name. When the data is read in,
the program will automatically scale x and y limits if "Auto" is on.
If you had it off, simply hit F9 to autoscale x and y. The number of
points will automatically be updated to reflect your data. If you try
to read in more than 500 points, the data will be truncated. You can
overcome this however by creating a configuration file and then
editing it. See the section following the "alt z" description above.

WRITING A FUNCTION (STRING) TO DISK:
Enter a function, press Ctrl f, then enter a file name. Your function
(string) will be appended to that file. A file will be created if none
exits.

READING A FUNCTION FROM DISK:
Go to an unused stack position if desired. Press Alt f, enter a file
name.  You are now "viewing" that file, line by line.  Simply press ENTER
and that line will be read in. Note that in the sample file "func.fcn", I
include "comment" lines. These are treated just like function strings,
eg. you can (accidentally) read them in. No harm, just delete it and
start over.  You can, by the way, write your own comment lines, by typing
in a "function" which is really a comment (don't try to use F2!!).  Then
use Ctrl f and write this comment to a file. Of course you can also use
an editor outside the program to create/edit a function file. I had some
trouble doing this because some editors embed different control
characters in files. (end of file character, end of line character, etc.)
What function plotter "needs" is one CR and one LF character after EACH
line. (CR = carriage return, LF = line feed). Here is an example of how
you can get into trouble. You create a new function file using (say)
Sidekick Plus (TM). It puts an end of file character at the end of your
file. In function plotter you append a few lines of functions.  You exit
function plotter and bring up Sikekick to look at your file and you don't
see your new lines. What happened? Well, Sidekick will ignore anything
after the EOF mark, and that's exactly where you appended your lines.

SHAREWARE

If you find this program useful, please register. Your support is vital
and has a number of benefits. You will be put on the mailing list for
future upgrades. They will be mailed to you for a nominal fee or for free
if you send a stamped, self-addressed mailer and disk. Your questions,
submitted in writing will be answered. A printed manual will be available
in the future and will only be offered to registered users. Please send
your registration fee of $20 to: (also questions, comments)

Robert G. Kaires
609 Glover Dr.
Runnemede, NJ  08078