PLOT - Version 1.50 June 12, 1991 =================== 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,1991. PLOT is freely distributable provided this document is distributed with the executable file PLOT150.PRG. Reports of problems, bugs or suggestions are welcome. ********************************************************************** New Stuff (since v1.2) ********************************************************************** PLOT v1.50: Several new features have been added: 1. pi (=3.14159...) can be used in function entry, though not when you're being prompted for a *constant*. Thus, for example, pi/2*cos(pi*x/2) is a legal function entry, but (unfortunately) xupper=pi/2 is not allowed. 2. A function history buffer is now built in, so that (up to 20) previously entered functions can be scrolled through with the up/down arrow keys when you're being prompted for function entry. 3. A new menu item, Numeric, appears on the alternate (GEM) screen. Here you'll find several useful utilities: Calculator: An expression evaluator. Just type in any (numerical) expression, such as sin(22), 2.5*bsj(0,pi/2), etc. and the result will be displayed. If an 'x' appears anywhere it will be taken to be 0. Zeros: Computes zeros for functions entered at the keyboard. e.g. you could enter the function (at the y: prompt) 'x^2-9', or something much more complicated. You will also have to enter the beginning and end of the x-interval (x1 and x2) which will be searched, and specify if one (option 0) or 'all' (option 1) roots are wanted. What does this mean? Well, if all roots are requested (the default case), the grain setting (defaults to 100) is used to divide the interval (x1,x2) into sub-intervals and any sub-intervals for which the function has opposite sign at the two ends will result in a zero being found. If only one zero is requested, the first zero will be located (assuming f(x1)*f(x2) < 0). Integration: A numerical integration routine, using 20 point Gaussian quadrature in each panel. The number of panels into which the interval is divided has a default value of 1, but can be altered easily. If more than 10 panels are set, intermediate (cumulative) results are shown after each 10 panel set is completed. In most cases, you'll soon find that accuracy is rarely increased by setting more than 1 or at most a few panels. Polynomial Roots: Here a polynomial (of degree up to size 20) can be entered. Only monomials (functions of a single variable) are allowed, but the coefficients may be complex. The (possibly complex) roots are then computed and displayed. While in any of these numerical utilities, screen output may be paused (usually) by pressing any key (other than Escape - see next sentence) (any key resumes). Pressing aborts the current operation. For example, if you want to cut short the computation of zeros of some function, pressing aborts and returns you to the function entry line. Also: Fixed a bug whereby a (c)ontinue after printing hardcopy (with GDOS) messed up screen output (some plot size parameters needed resetting after the workstation output). PLOT v1.42: Fixed a small problem where sometimes the user would be prompted for curve printing even when no curves had been saved for printing. This only happened after a (c)ontinue sequence. PLOT v1.41: The Help screens (accessible by pressing the key) are now available at the ArrayOps screen. Changed the default printer device number (for GDOS) to 21 for the high resolution screen (it used to be set to 23). Now 21 is used for both cases: monochrome and colour monitors. PLOT v1.34: Corrected a problem where there was some confusion as to whether the data editor should show the transformed or untransformed data. Found that the GFA Interpreter has a bug to do with arrays, but things are OK in the compiled version. Same problem occurs with the 3.5E interpreter. PLOT v1.33: Fixed some problems with line thicknesses for the curves occasionally interfering with box frame thickness. PLOT v1.30: Changed method of inputting plotting box parameters (xlower..yupper, line style, etc.) from the 'line at a time' approach to a full screen editing approach. Now a single accepts all the defaults and gets on with the job. PLOT v1.26: Added save to disk feature for coordinate pairs read off the plot. PLOT v1.25: Added save to disk feature for the polynomial fit parameters. PLOT v1.23: rim feature added to editor. This enables a data array to be reduced (trimmed) in size. In the data editor, pressing the key puts up a small box in which four parameters are set. These are: (1) nstart - the number of the first data point to be retained. (2) nstop - the number of the last data point to be retained (with a possible exception if lastpoint is set). (3) ntrim - the trim spacing. E.g. if nstart=2 and ntrim=3, then every third point will be retained, starting with the second. Thus the points retained in this example are 2,5,8,... . (4) lastpoint - Setting this to 1 forces the last (of the original data set) point to be retained; leaving it at the default of 0 means that the trimmed array will terminate at whatever data pair occurs at a value of nstart+(integer)*ntrim which is less than or equal to nstop. Note that this trimming procedure can be used to delete any contiguous blocks of data, by using ntrim=1 and suitable values for nstart and nstop. The deletions occur only in memory, not on disk. They cannot be undone, except by reading in the disk file again. ********************************************************************** 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. The present version (Plot 1.50) is compiled in GFA v3.5E. 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 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: to clear the field, Delete, Backspace and Arrow keys all work; in addition takes you to the beginning of the input string and 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. and move to the beginning and end, respectively, of the input field. 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: 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 = 10,000 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. The line thickness 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: HVS(x) is defined to be equal to 1 for x >= 0 and to be 0 for x < 0.). 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. [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 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. After clicking the mouse at a point on the plot, if you press the key, a little message will flash on the screen saying 'saved'. This means that the coordinates of that point have been recorded for possible later saving in a disk file. When you exit coordinate mode with another , if any 'saves' have been made you will be asked if you really want to save a file and then be prompted for a disk file name (in an item selector box - the default extension .COO doesn't have to be used); the file is a simple ascii file with a list of the coordinate pairs selected. 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 gives access to the built-in 8 help screens, as usual. (b). Pressing 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; it is set to 21 by default. (c). Pressing enters legend mode. You will be prompted to enter some text. When done press 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 to 'paste' down your choices, or to remove all the legends just deposited. You can press again to add further legends or proceed to step (d). (d). Pressing 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: Just pressing at the Array Ops menu gives this by default. 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 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 . (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! However, the polynomial coefficients can optionally be saved into a file before leaving this screen. 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 (the number used in your ASSIGN.SYS file) is 21 - 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 LQ500) 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 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 (default: 21). 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 ; if you're doing this then of course you must also comment out the LQ800.SYS portion of the ASSIGN.SYS file below. 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 21 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 can be 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.