This is Info file plotutils.info, produced by Makeinfo-1.63 from the
input file ./plotutils.texi.

   This file documents version 1.3 of the GNU plotutils package.

   Copyright (C) 1989-1997 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: plotutils.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

   This is the documentation for version 1.3 of the GNU plotutils
(plotting utilities) package.  The package consists of programs and
functions for data plotting and vector graphics.

* Menu:

* Introduction::        About the GNU plotutils package
* graph Examples::	Using GNU graph to plot datasets
* graph Invocation::	GNU graph command-line options
* Plot Filters::	Converting the output of graph to other formats
* libplot::             A library for device-independent 2-d vector graphics
* spline Examples::     Using GNU spline to perform interpolation
* spline Invocation::   GNU spline command-line options
* ode::			ode, a differential equation integrator
* Appendices::          Additional Information


File: plotutils.info,  Node: Introduction,  Next: graph Examples,  Prev: Top,  Up: Top

The GNU Plotting Utilities
**************************

   The GNU plotting utilities include programs for plotting
two-dimensional scientific data.  They are built on top of GNU
`libplot', a library for device-independent two-dimensional vector
graphics.  The most important plotting programs are the programs
collectively known as `graph' (`graph-X', `graph-ps', `graph-fig',
`graph-tek', and raw `graph').  Each of the versions of `graph' reads
one or more data files containing datasets, and outputs a plot.  The
plot may be directed to a display device or to a file.  The versions of
`graph' differ only in the display device they produce output for.

   `graph-X' pops up a window on an X Window System display, and draws
the plot in it.  `graph-ps' produces a plot in encapsulated Postscript
format that may be included in another document, sent to a printer, or
edited with the `idraw' drawing editor.  `graph-fig' produces output
that may be displayed and edited with the `xfig' drawing editor.
`graph-tek' produces output that may be displayed on a Tektronix 4014
terminal or emulator.  Raw `graph' produces output in a
device-independent format, referred to below as a GNU graphics
metafile; it may be translated into other formats.  When discussing the
common features of these five programs, we refer to them simply as
`graph'.

   `graph' can read datasets in both ASCII and binary format, and
datasets in the `table' format produced by the plotting program
`gnuplot'.  It produces a plot with or without axes and labels.  You
may specify labels and ranges for the axes, and you may set the size
and position of the plot on the display device.  The labels may contain
subscripts and subscripts, Greek letters, and other special symbols;
there is also support for Cyrillic script (i.e., Russian) and Japanese.
You may specify the type of plotting symbol used for each dataset, and
such parameters as the style and thickness of the line, if any, used to
connect points in a dataset.  The plotting of filled regions is
supported, as is the drawing of error bars.  `graph' provides full
support for multiplotting.  With a single invocation of `graph', you
may produce a plot consisting of many sub-plots, either side by side or
inset.  Each sub-plot will have its own axes and data.

   The versions `graph-X', `graph-tek', and raw `graph' have a feature
which most plotting programs do not have.  They can accept input from a
pipe, and plot data points in real time.  For this to occur, the user
must specify ranges for both axes, so that `graph' does not have to
wait until the end of input to determine them.

   Accompanying `graph' are five `plot filters' collectively called
`plot'.  They translate device-independent GNU graphics metafiles
(produced for example by raw `graph') into the five just-mentioned
output formats.  Versions of `plot' include `plot2X', `plot2ps',
`plot2fig', `plot2tek', and `plot2plot'.  These programs are useful if
you wish to produce output in several different formats while invoking
`graph' only once.  They are also useful if you wish to translate files
in the traditional `plot(5)' format produced by, for example, the
non-GNU versions of `graph' provided with some operating systems.  GNU
metafile format is compatible with the traditional `plot(5)' format.

   Among the other GNU plotting utilities, `spline' does spline
interpolation of data.  It normally uses either cubic spline
interpolation or exponential splines in tension, but like `graph' it
can function as a real-time filter under some circumstances.  `ode'
provides the ability to integrate an ordinary differential equation, or
a system of ordinary differential equations, when provided with an
explicit expression for each equation.  It supplements the plotting
program `gnuplot', which can plot functions but not integrate ordinary
differential equations.

   Distributed as a part of this package is GNU `libplot', the function
library mentioned above.  It is the function library for
device-independent two-dimensional vector graphics on which `graph' and
`plot' are based.  There are five versions of this library: `libplotX',
`libplotps', `libplotfig', `libplottek', and raw `libplot'.  The first
four of these produce, respectively, output for X Window System
displays, output in encapsulated Postscript format that may be included
in another document, sent to a printer, or edited with the `idraw'
drawing editor, output that may be displayed and edited with the `xfig'
drawing editor, and output that may be displayed on a Tektronix 4014
terminal or emulator.  Raw `libplot' produces output in the
device-independent GNU graphics metafile format.

   All versions of `libplot' provide the ability to draw such objects
as lines, open and closed polylines, arcs (both circular and elliptic),
circles and ellipses, markers, and text strings.  The filling of objects
other than text strings is supported (fill color, as well as pen color,
may be set arbitrarily).  A wide variety of line types and marker
symbols is supported.  The support for drawing text strings is
extensive.  `libplotX', `libplotps', and `libplotfig' support the 35
standard Postscript fonts, and all three, together with `libplottek',
support a set of 16 Hershey vector fonts, including HersheyCyrillic.
Text strings may include subscripts and superscripts, and may include
characters chosen from more than one font in a typeface.  They may
include many non-alphanumeric characters.  The entire collection of
1641 `Hershey glyphs' digitized c. 1967 by Dr. Allen V. Hershey at the
U.S. Naval Surface Weapons Center, which includes many curious symbols,
is built into `libplot'.  Japanese text strings in the so-called EUC
(Extended Unix Code) format may be also be drawn.  Such strings may
include both syllabic characters (Hiragana and Katakana) and
ideographic characters (Kanji).  A library of 603 Japanese Kanji
digitized by Dr. Hershey is built into `libplot'.

   The drawing editors `idraw' and `xfig' are not distributed along
with the GNU plotting utilities.  They are freely distributable, and you
may obtain them elsewhere (*note Auxiliary Software::.).


File: plotutils.info,  Node: graph Examples,  Next: graph Invocation,  Prev: Introduction,  Up: Top

The `graph' Utility
*******************

   Each invocation of `graph' reads one or more datasets from files
named on the command line or from standard input, and prepares a plot.
There are many command-line options for adjusting the visual appearance
of the plot.  The following sections explain how to use the most
frequently used options, by giving examples.

* Menu:

* Simple Examples::	Simple examples using graph
* Multiple Datasets::	Preparing a plot from more than one dataset
* Non-Square Plots::	Changing the aspect ratio of a plot
* Multiplotting::	Multiple plots on a single page
* Data Formats::	Reading binary and other data formats


File: plotutils.info,  Node: Simple Examples,  Next: Non-Square Plots,  Prev: graph Examples,  Up: graph Examples

Simple examples using `graph'
=============================

   By default, `graph' reads ASCII data from the files specified on the
command line, or from standard input if no files are specified.  The
data are pairs of numbers, interpreted as the x and y coordinates of
data points:

     0.0  0.0
     1.0  0.2
     2.0  0.0
     3.0  0.4
     4.0  0.2
     5.0  0.6

Data points do not need to be on different lines, nor do the x and y
coordinates of a data point need to be on the same line.  However,
there should be no blank lines in the input if it is to be viewed as
forming a single dataset.

   To plot such a dataset with one of the versions of `graph', you
could do

     graph-ps ascii_data_file > plot.ps

or equivalently

     graph-ps < ascii_data_file > plot.ps

This will produce an encapsulated Postscript file `plot.ps', which you
may include in another document, print, view, or edit with the `idraw'
drawing editor.  You may also do

     graph-fig < ascii_data_file > plot.fig

if you wish to produce a file `plot.fig' that you may edit with the the
`xfig' drawing editor.

   You may use `graph-X' instead of `graph-ps' or `graph-fig' if you
wish to pop up a window on an X Window System display, and display the
plot in it.  For that, you would do

     graph-X < ascii_data_file

If you use `graph-X', no output file will be produced; only a window.
The window will close if you type `q' or click your mouse in it.

   You may also use `graph-tek', to display a plot on a device that can
emulate a Tektronix 4014 graphics terminal.  `xterm', the X Window
System terminal emulator, can do this.  Within an `xterm' window, you
would do

     graph-tek < ascii_data_file

`xterm' normally emulates a VT100 terminal, but when this command is
issued from within it, it will pop up a second window (a `Tektronix
window') and draw the plot in it.  The Japanese terminal emulator
`kterm' should be able to do the same, provided that it is correctly
installed.  Another piece of software that can emulate a Tektronix 4014
terminal is the DOS version of `kermit'.

   Of the five versions of `graph', `graph-tek' and `graph-X' may
behave differently depending on the environment in which they are
invoked.  This refers to the values taken by the `TERM' and `DISPLAY'
environment variables, in particular.  For a discussion of the effects
of the environment on `graph-tek' and `graph-X', *note Environment::..
The following remarks apply to plots drawn with any of the versions of
`graph'.

   By default, successive points in the dataset are joined by solid line
segments, which form a polygonal line that we call simply a `line'.  You
may choose the style of line (the `linemode') with the `-m' option:

     graph-ps -m 2 < ascii_data_file > plot.ps

Here `-m 2' indicates that linemode #2 should be used.  If the dataset
is rendered in monochrome, which is the default, the line may be drawn
in one of five distinct styles.  Linemodes 1 through 5 signify solid,
dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence
repeats.  If the `-C' option is used, the dataset will be rendered in
color.  For colored datasets, the line may be drawn in one of 25
distinct styles.  Linemodes 1 through 5 signify red, green, blue,
magenta, and cyan; all are solid.  Linemodes 6 through 10 signify the
same five colors, but dotted rather than solid.  Linemodes 11 through 16
signify the same five colors, but dotdashed, and so forth.  After
linemode 25, the sequence repeats.  Linemode 0, irrespective of whether
the rendering is in monochrome or color, means that the line is not
drawn.

   If you wish to *fill* the polygon bounded by the line (i.e., shade
it, or fill it with a solid color), you may use the `-q' option.  For
example,

     echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph-ps -C -m 1 -q 0.3 > plot.ps

will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9),
and (0.9,0.1).  The repetition of the first vertex (0.1,0.1) at the end
of the sequence of vertices ensures that the square will be closed: all
four segments of its boundary will be drawn.  The square will be drawn
in red (since the colored version of linemode #1 is requested).  The
interior of the square will be filled with red to an intensity of 30%,
as the `-q 0.3' option indicates.  If the intensity were zero, the
region would be filled with white, and if it were 1.0, the region would
be filled with solid color.  If the intensity were negative, the region
would be unfilled, or transparent (the default).

   You may choose the width of the line, whether it is filled or not, by
using the `-W' option.  For example, `-W 0.01' means that the line
should have a width equal to 0.01 times the width of the display.
Also, you may put symbols at each data point along the line by doing,
for example,

     graph-ps -S 3 0.1 < ascii_data_file > plot.ps

where the first argument 3 indicates which symbol to plot.  The optional
second argument 0.1 specifies the symbol size as a fraction of the size
of the `plotting box': the square within which the plot is drawn.
Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk,
symbol #4 is a circle, symbol #5 is a cross, and so forth.  (*Note
Marker Symbols::.)  Symbols 1 through 31 are the same for all versions
of `graph', and the color of a symbol will be the same as the color of
the line it is plotted along.

   Actually, you would probably not want to plot symbols at each point
in the dataset unless you turn off the line joining the points.  For
this purpose, the `negative linemode' concept is useful.  A line whose
linemode is negative is not visible; however, any symbols plotted along
it will have the color associated with the corresponding positive
linemode.  So, for example,

     graph-ps -C -m -3 -S 4 < ascii_data_file > plot.ps

will plot a blue circle at each data point.  The circles will not be
joined by line segments.  By adding the optional second argument to the
`-S' option, you may adjust the size of the circles.

   `graph' will automatically generate abscissa (i.e., x) values for
you if you use the `-a' option.  If this option is used, no abscissa
values should be given in the data file.  The data points will be taken
to be regularly spaced along the abscissa.  The two arguments following
`-a' on the command line will be taken as the sampling interval and the
abscissa value of the first data point.  If they are absent, they
default to 1.0 and 0.0 respectively.  For example, the command

     echo 0 1 0 | graph-ps -a > plot.ps

produces exactly the same plot  as

     echo 0 0 1 1 2 0 | graph-ps > plot.ps

   `graph' will plot data with error bars, if the `-I e' option is
specified.  If it is, the dataset should consist of triples (x,y,error)
rather than pairs (x,y).  A vertical error bar of the appropriate
length will be plotted at each data point.  You may plot a symbol at
each data point, along with the error bar, by using the `-S' option in
the usual way.  The symbol will be the same for each point in the
dataset.  You may use the `-a' option in conjunction with `-I e', if
you wish.  If you do, the dataset should contain no abscissa (i.e., x)
values.

   By default the limits on the x and y axes, and the spacing between
the labeled ticks on each axis, are computed automatically.  You may
wish to set them manually.  You may accomplish this with the `-x' and
`-y' options.

     echo 0 0 1 1 2 0 | graph-ps -x -1 3 -y -1 2 > plot.ps

will produce a plot in which the x axis extends from -1 to 3, and the y
axis from -1 to 2.  By default, `graph' tries to place about six
numbered ticks on each axis.  By including an optional third argument
to either `-x' or `-y', you may manually set the spacing of these
ticks, also.  For example, using `-y -1 2 1' rather than `-y -1 2' will
produce a y axis with labeled ticks at -1, 0, 1, and 2, rather than at
the locations that `graph' would choose by default.  In general, if a
third argument is present then labeled ticks will be placed at each of
its integer multiples.

   To make an axis logarithmic, you may use the `-l' option.  For
example,

     echo 1 1 2 3 3 1 | graph-ps -l x > plot.ps

will produce a plot in which the x axis is logarithmic, but the y axis
is linear.  To make both axes logarithmic, you would use `-l x -l y'.
By default, the upper and lower limits on a logarithmic axis are powers
of ten, and the tick marks at these powers of ten, and no other tick
marks, are labeled.  If you need more labeled ticks on a logarithmic
axis, you should specify a tick spacing manually.  For example, `-l x
-x 1 9 2' will produce a plot in which the x axis is logarithmic and
extends from 1 to 9.  Labeled ticks will be located at each integer
multiple of 2, i.e., at 2, 4, 6, and 8.

   You may label the x and y axes with the `-X' and `-Y' options,
respectively.  For example,

     echo 1 1 2 3 3 1 | graph-ps -l x -X "A Logarithmic Axis" > plot.ps

will label the log axis in the preceding example.  By default the label
for the y axis, if any, will be rotated ninety degrees, unless you use
the `--toggle-rotate-y-label' option.  You may specify a `top label',
or title for the plot, by using the `-L' option.  Doing, for example,

     echo 1 1 2 3 3 1 | graph-ps -l x -L "A Simple Example" > plot.ps

will produce a plot with a title on top.

   The size of the x axis and y axis labels is specified with the `-f'
option, and the size of the title is specified with the
`--title-font-size' option.  For example,

     echo 1 1 2 3 3 1 | graph-ps -X "Abscissa" -f 0.1 > plot.ps

will produce a plot in which the font size of the x axis label, and
each of the numerical tick labels, is very large (0.1 times the size of
the plotting box, i.e., the square within which the plot is drawn).

   The font in which the labels specified with the `-X', `-Y', and `-L'
options are drawn may be specified with the `-F' option.  For example,
`-F Times-Roman' will make the labels appear in Times-Roman instead of
the default font (which is Helvetica, for versions of `graph' other
than `graph-tek').  Font names are case-insensitive, so `-F
times-roman' will work equally well.  There are 51 fonts available
in all.  This includes 35 Postscript fonts (for all versions of `graph'
other than `graph-tek') and 16 Hershey fonts.  The Hershey fonts
include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese.
For a discussion of the available fonts, *note Text Fonts::..

   The format of the labels drawn with the `-X', `-Y', and `-L' options
may be quite intricate.  Subscripts, superscripts, square roots, and
switching fonts within a typeface are all allowed.  The above examples
do not illustrate this, but for details, *note Text String Format::..

   Each of the preceding examples produced a plot containing the default
sort of grid (a square box, with ticks and labels drawn along its lower
edge and its left edge).  There are actually several sorts of grid you
may request.  The `-g 0', `-g 1', `-g 2', and `-g 3' options yield
successively fancier grids.  What they yield, respectively, is no grid
at all, a pair of axes with ticks and labels, a square box with ticks
and labels, and a square box with ticks, labels, and grid lines.  As
you can see, `-g 2' is the default.  There is also a `-g 4' option,
which yields a slightly different sort of grid: a pair of axes that
cross at the origin.  This last sort of grid is useful if the x or y
coordinates of the data points you are plotting are both positive and
negative.


File: plotutils.info,  Node: Non-Square Plots,  Next: Multiple Datasets,  Prev: Simple Examples,  Up: graph Examples

Non-square and displaced plots
==============================

   To alter the linear dimensions of a plot, and also to position it in
a different part of your display, you could do something like

     graph-ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps

Here the `-h' and `-w' options specify the height and width of the
plotting box, and the `-r' and `-u' options indicate how far up and to
the right the lower left corner of the plotting box should be
positioned.  All dimensions are expressed as fractions of the size of
the graphics display, which is nominally square.  By default, the height
and width equal 0.6, and the `upward shift' and the `rightward shift'
equal 0.2.  So the above example will produce a plot that is half as
tall as usual.  Compared to its usual position, the plot will be shifted
slightly downward and to the left.

   The `graphics display', within which the plotting box is located, is
an abstraction.  For `graph-X', the graphics display is a square window
on an X display.  For `graph-ps', it is a square region centered on an
8.5in by 11in page, occupying the full width of the page.  For
`graph-fig', it is a square region with edge length 8.5in, in the upper
left corner of an `xfig' display.  And for `graph-tek', it is the
square region occupying the left two thirds of a Tektronix display.
(Tektronix displays are 1.5 times as wide as they are high.)

   In any of the versions of `graph', changing the width of the
plotting box may have unforeseen consequences.  A number of command-line
options specify sizes or dimensions as fractions of the width of the
plotting box.  For example, `-S 3 .01' specifies that the plotting
symbols for the following dataset should be of type #3, and should have
a fractional size equal to 0.01.  If the `-w' option is employed to
widen or narrow the plot, such dimensions or sizes will scale in tandem.
That is presumably the right thing to do, but may be slightly
disconcerting.


File: plotutils.info,  Node: Multiple Datasets,  Next: Multiplotting,  Prev: Non-Square Plots,  Up: graph Examples

Preparing a plot from more than one dataset
===========================================

   It is frequently the case that several datasets need to be displayed
on the same plot.  If so, you may wish to distinguish the points in
different datasets by joining them by lines of different types, or by
using plotting symbols of different types.

   A more complicated example would be the following.  You may have a
file containing a dataset that is the result of experimental
observations, and a file containing closely spaced points that trace
out a theoretical curve.  The second file is a dataset in its own
right.  You would presumably plot it with line segments joining
successive points, so as to trace out the theoretical curve.  But the
first dataset, resulting from experiment, would be plotted without such
line segments.  In fact, a plotting symbol would be plotted at each of
its points.

   These examples, and others like them, led us to define a set of seven
*attributes* which define the way in which a dataset should be plotted.
These attributes, which may be set by command-line options, are the
following.

  1. color/monochrome

  2. linemode

  3. linewidth

  4. symbol type

  5. symbol size

  6. symbol font name

  7. fill fraction

Color/monochrome (a choice of one or the other) is the simplest.  This
choice is toggled with the `-C' option.  The `linemode' (i.e., line
style) specifies how the line segments joining successive points should
be drawn; it is specified with the `-m' option.  Linemode #0 means no
linemode at all, for example.  `Linewidth' is self-explanatory; it is
specified with the `-W' option. `Symbol type' and `symbol size', which
are specified with the `-S' option, specify the symbol plotted at each
point of the dataset.  `Symbol font name' refers to the font from which
plotting symbols #32 and above, which are taken to be characters rather
than geometric symbols, are selected.  It is set with the
`--symbol-font-name' option, and is relevant only if `-S' is used to
request such special plotting symbols. Finally, the polygonal line
joining the points in a dataset may be *filled*, to create a filled or
shaded polygon.  The `fill fraction' is set with the `-q' option.
A negative fill fraction means no fill, or transparent; zero means
white, and 1.0 means solid, or fully colored.

   The preceding seven attributes refer to the way in which datasets are
plotted.  Datasets may also differ from one another in the way in which
they are read from files.  The dataset(s) in a file may or may not
contain error bars, for example.  If a file contains data with error
bars, the `-I e' option should occur on the command line before the file
name.  (The `-I' option specifies the input format for the following
files.)

   The following illustrates how datasets in three different input files
could be plotted simultaneously.

     graph-ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps

The dataset in `file_1' will be plotted in line style #0, so successive
points will not be joined by lines.  But symbol #3 (an asterisk) will
be plotted at each point.  The dataset in `file_2' will be plotted in
color, and linemode #3 will be used.  In color plotting, linemode #3 is
interpreted as a solid blue line.  The second `-C' on the command line
turns off color for `file_3'.  The points in the third dataset will be
joined by a black line of width 0.02, as a fraction of the width of the
graphics display.

   The above command line could be made even more complicated by
specifying additional options (e.g., `-q' or `-I') before each file.
In fact the command line could also include such standard options as
`-x' or `-y', which specify the range of each axis.  Such options,
which refer to the plot as a whole rather than to individual datasets,
should appear before the first file name.  For example, you could do

     graph-ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps

Note that it is possible to include the special file name `-', which
refers to standard input, on the command line.  So you may produce a
plot in part from files, and in part from input that is piped to
`graph' from another program.

   Each input file may include more than one dataset.  If so, the
command line options preceding a file on the command line will take
effect for all datasets in that file.  There are two exceptions to
this.  By default, the linemode is incremented (`bumped') from one
dataset to the next.  This feature is usually quite convenient.  For
example, if you do

     graph-ps -m 3 file_1 > output.ps

the first dataset in `file_1' will appear in linemode #3, the second in
linemode #4, etc.  In fact if you do

     graph-ps file_1 file_2 ... > output.ps

without specifying linemode explicitly, the successive datasets read
from the files on the command line will appear in linemode #1, linemode
#2, ....  If you do not like this feature, you may turn it off, or in
general toggle it, by using the `-B' option.

   You may also control manually the linemode and symbol type used for
the datasets within any file.  You would do this by including
directives in the file itself, rather than on the command line.  For
example, if the line

     #m=-5,S=10

appeared in an ASCII-format input file, it would be interpreted as a
directive to switch to linemode #-5 and symbol type #10 for the
following dataset.  Future releases of `graph' may provide the ability
to set each of the seven dataset attributes in this way.


File: plotutils.info,  Node: Multiplotting,  Next: Data Formats,  Prev: Multiple Datasets,  Up: graph Examples

Multiplotting: placing multiple plots on a single page
======================================================

   It is occasionally useful to display several plots at once on a
single page, or on a single graphics display.  We call such a composite
plot a *multiplot*.  One common sort of multiplot is a small plot inset
into a larger one.  Another sort is two or more plots side by side.

   `graph' can draw multiplots consisting of an arbitrarily large
number of sub-plots.  When multiplotting, `graph' draws each sub-plot
in its own `virtual display'.  When a conventional plot is drawn, the
virtual display is the same as the physical display.  But when a
multiplot is drawn, the virtual display may be any smaller square
region.

   The following example illustrates the idea.  For the present
purposes, the physical display is a square with lower left corner
(0.0,0.0) and upper right corner (1.0,1.0).

     graph-ps data_file_1 --reposition 0.35 0.35 0.3 data_file_2

Here `data_file_1' is plotted in the usual way.  The virtual display is
then shrunk to a square of size 0.3, with lower left corner
(0.35,0.35).  A plot is then prepared from `data_file_2', and drawn.
This plot, as you can see, will be a much smaller plot that is inset
into the first plot.

   By convention, before each sub-plot of a multiplot other than the
first is drawn, a `blankout region' surrounding its plotting box is
erased.  (That is, it is filled with white.)  This erasure prevents the
sub-plots from overlapping and producing a messy result.  By default,
the blankout region is a rectangular region 30% larger in each dimension
than the plotting box for the sub-plot.  This is appropriate if the
sub-plot is a small one that is inset into the first sub-plot.  It may
not be appropriate, however, if you are preparing a multiplot in which
several sub-plots appear side by side.  You may use the `--blankout'
option to adjust this parameter.  For example, specifying `--blankout
1.0' will make the blankout region for a sub-plot coincide with its
plotting box.  Specifying `--blankout 0.0' will prevent any blanking
out from occurring.  The blankout parameter may differ from sub-plot to
sub-plot.

   It should be emphasized that every sub-plot in a multiplot is a plot
in its own right.  All the usual options (`-m', `-S', `-x', `-y', etc.)
may be applied to each sub-plot separately.  The options for a sub-plot
should occur on the `graph' command line immediately after the
`--reposition' option that applies to it.  Each sub-plot may be
prepared from more than a single dataset, also.  The names of the data
files for each subplot should occur on the command line before the
following `--reposition' option, if any.


File: plotutils.info,  Node: Data Formats,  Prev: Multiplotting,  Up: graph Examples

Reading binary and other data formats
=====================================

   By default, `graph' reads datasets in ASCII format.  But it can also
read datasets in binary (double precision floating point) format.  For
this, the `-I d' option must be specified.  There are two advantages to
using binary data: 1) `graph' runs significantly faster because the
computational overhead for converting data from ASCII to binary is
eliminated, and 2) the input files may be significantly smaller than
the ASCII format would be.  If you have very large datasets, using
binary format may reduce storage and runtime costs.

   For example, you may create a binary dataset as output from a C
language program:

     #include <stdio.h>
     void write_point (double x, double y)
     {
       fwrite(&x, sizeof (double), 1, stdout);
       fwrite(&y, sizeof (double), 1, stdout);
     }

You may plot data written this way by doing:

     graph-ps -I d < binary_data_file > plot.ps

The inclusion of multiple datasets within a single binary file is
supported.  If a binary file contains more than a single dataset,
successive datasets should be separated by a single occurrence of the
quantity `MAXDOUBLE', which is the largest possible double precision
floating point number.  On most machines this is approximately
1.8x10^308.

   If you are reading datasets from more than one file, it is not
required that the files be in the same format.  For example,

     graph-ps -I d binary_data_file -I a ascii_data_file > plot.ps

will read `binary_data_file' in `d' (binary double precision) format,
and `ascii_data_file' in `a' (normal ASCII) format.

   There is currently no support for reading and plotting binary data
with error bars.  If you have data with error bars, you should supply
the data to `graph' in ASCII, and use the `-I e' option.

   `graph' can also read data files in the `table' format produced by
the `gnuplot' plotting program.  For this, you should use the `-I g'
option.  Such a data file may consist of more than one dataset.

   To sum up: there are four data formats, `a' (normal ASCII), `e'
(ASCII with error bars), `d' (binary double precision), and `g' (the
`table' format produced by `gnuplot').  Input files may be in any of
these four formats.


File: plotutils.info,  Node: graph Invocation,  Next: Plot Filters,  Prev: graph Examples,  Up: Top

`graph' command-line options
============================

   The command-line options to `graph' are listed in the following
sections.  Each option that takes an argument is followed, in
parentheses, by the type and default value of the argument.  There are
five sections, because there are five sorts of option.  They are:

* Menu:

* Plot Options::	Options affecting an entire plot
* Dataset Options::	Options affecting the reading and plotting of datasets
* Multiplot Options::	Options for drawing several plots at once
* Raw graph Options::	Options meaningful only for raw graph
* Info Options::	Options requesting information (e.g., --help)


File: plotutils.info,  Node: Plot Options,  Next: Dataset Options,  Prev: graph Invocation,  Up: graph Invocation

Plot options
------------

   The following options affect an entire plot.  They should appear on
the command line before the first filename.  They should appear at most
once on the command line, unless a multiplot is being drawn, in which
case they may appear after each `--reposition'.

`-f FONT_SIZE'
`--font-size FONT_SIZE'
     (Float, default 0.0525.)  Set the size of the font used for the
     axis and tick labels, as a fraction of the size of the box framing
     the plot, to be FONT_SIZE.

`-F FONT_NAME'
`--font-name FONT_NAME'
     (String, default "Helvetica" except for `graph-tek', for which
     "HersheySerif" is the default.)  Set the font used for the axis
     and tick labels, and for the plot title (if any), to be FONT_NAME.
     The choice of font for the plot title may be overridden with the
     `--title-font-name' option (see below).  Font names are
     case-insensitive.  For a list of available fonts, *note Text
     Fonts::..  If the font is not available, the default font will be
     used.

`-g GRID_STYLE'
`--grid-style GRID_STYLE'
     (Integer, default 2.)  Set the grid style for the plot to be
     GRID_STYLE.  Grid styles 0 through 3 are progressively more fancy,
     but style 4 is a somewhat different style.

       0. no axes, tick marks or labels.

       1. a pair of axes, with tick marks and labels.

       2. box around plot, with tick marks and labels.

       3. box around plot, with tick marks and labels; also grid lines.

       4. axes intersect at the origin, with tick marks and labels.

`-h HEIGHT'
`--height-of-plot HEIGHT'
     (Float, default 0.6.)  Set the fractional height of the plot with
     respect to the height of the display (or virtual display, in the
     case of a multiplot) to be HEIGHT.  A value of 1.0 will produce a
     plotting box which fills the available area.  Note that the tick
     marks and labels are outside the plotting box, so that values less
     than 1.0 are generally used.

`-K CLIP_MODE'
`--clip-mode CLIP_MODE'
     (Integer, default 1.) Set the clip mode for the plot to CLIP_MODE.
     The clip mode is relevant only if data points are being joined by a
     line, and the line is not being filled to create a filled region
     (since filled regions are clipped in a fixed way).  There are
     three clip modes: 0, 1, and 2.  Clip mode 0 means that a line
     segment joining two data points will be plotted only if neither
     point is outside the plotting box.  Clip mode 1 means that it will
     be plotted if no more than one of the two points is outside, and
     clip mode 2 means that it will be plotted even if both are
     outside.  In all cases the line segment will be clipped to the
     plotting box.

`-L TOP_LABEL'
`--top-label TOP_LABEL'
     (String, default empty.)  Place the text string TOP_LABEL above
     the plot, as a plot title.  The string may include escape sequences
     (*note Text String Format::.).  The `--title-font-size' option may
     be used to specify the size of the font.  The font is normally the
     same as the font used for labelling axes and tick labels, as
     selected by the `-F' option.  But this may be overridden with the
     `--title-font-name' option.

`-l X|Y'
`--toggle-log-axis X|Y'
     Set the specified axis to be a log axis rather than a linear axis,
     or vice versa.  By default, both axes are linear axes.

`-N X|Y'
`--toggle-no-ticks X|Y'
     Toggle the presence of ticks and tick labels on the specified axis.
     This applies to the grid styles that normally include ticks and
     tick labels, i.e., grid styles 1, 2, 3, and 4.

`-R X|Y'
`--toggle-round-to-next-tick X|Y'
     Toggle the rounding of the limits of the specified axis, so that
     they are integer multiples of the spacing between labeled tick
     marks.  By default this does not take place if the user uses the
     `-x' or `-y' options to set axis limits explicitly.

`-r RIGHT'
`--right-shift RIGHT'
     (Float, default 0.2.)  Move the plot to the right by a fractional
     amount RIGHT with respect to the width of the display (or virtual
     display, in the case of a multiplot).  This produces a margin on
     the left side of the plotting box.  A value of 0.5 will produce a
     margin half the width of the available area.  Note that the tick
     marks and labels are drawn in the margin.

`-s'
`--save-screen'
     Save the screen. This option prevents `graph' from erasing the
     previous contents of the display device.  This is meaningful only
     for `graph-tek' and raw `graph'.  It may be employed to perform a
     crude sort of multiplotting.

`-T TICK_SIZE'
`--tick-size TICK_SIZE'
     (Float, default .02.) Set the fractional size of the tick marks on
     each axis to be TICK_SIZE.  A value of 1.0 produces tick marks on
     the x axis whose length is equal to the width of the plotting box.
     A negative TICK_SIZE will yield tick marks that extend outside
     the box, rather than inside.

`-t'
`--toggle-transpose-axes'
     Transpose the abscissa and ordinate.  This causes the axes to be
     interchanged, and the options that apply to each axis to be
     applied to the opposite axis.  That is, data points are read in as
     (y, x) pairs, and such options as `-x' and `-X' apply to the y
     axis rather than the x axis.  If the `-I e' option is in force, so
     that the data points are read with error bars, the orientation of
     the error bars will be switched between vertical and horizontal.

`-u UP'
`--upward-shift UP'
     (Float, default 0.2.)  Move the plot up by a fractional amount UP
     with respect to the height of the display (or virtual display, in
     the case of a multiplot).  This produces a margin below the
     plotting box.  A value of 0.5 will produce a margin half the
     height of the available area.  Note that the tick marks and labels
     are drawn in the margin.

`-w WIDTH'
`--width-of-plot WIDTH'
     (Float, default 0.6.) Set the fractional width of the plot with
     respect to the width of the display (or virtual display, in the
     case of a multiplot) to be WIDTH.  A value of 1.0 will produce a
     plotting box that fills the available area.  Note that the tick
     marks and labels are outside the plotting box, so values less than
     1.0 are generally used.

`-x [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
`--x-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
     (Floats.) The arguments LOWER_LIMIT and UPPER_LIMIT specify the
     limits of the x axis, and the optional argument SPACING specifies
     the spacing of labeled ticks along the axis.  If any of the three
     arguments is missing, it is computed from the data.  The arguments
     LOWER_LIMIT and UPPER_LIMIT must be present if `graph' is to act
     as a real-time filter.

`-y [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
`--y-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]'
     (Floats.)  The arguments specify the limits of the y axis, and the
     spacing of labeled ticks along it, as for the x axis (see above).
     The arguments LOWER_LIMIT and UPPER_LIMIT must be present if
     `graph' is to act as a real-time filter.

`-X X_LABEL'
`--x-title X_LABEL'
     (String, default empty.)  Set the label for the x axis to be the
     text string X_LABEL.  The string may include escape sequences
     (*note Text String Format::.).  The `-F' and `-f' options may be
     used to specify the name of the font and the size of the font.

`-Y Y_LABEL'
`--y-title Y_LABEL'
     (String, default empty.) Set the label for the y axis to be the
     text string Y_LABEL.  The string may include escape sequences
     (*note Text String Format::.).  The label will be rotated by ninety
     degrees so that it is parallel to the axis, unless the
     `--toggle-rotate-y-label' option is used.  Some old X Window System
     displays do not support rotated labels, and require the
     `--toggle-rotate-y-label' option.  The `-F' and `-f' options may
     be used to specify the name of the font and the size of the font.

`--frame-color NAME'
     (String, default "black".)  Set the color used for drawing the plot
     frame, and for drawing monochrome datasets if any, to be NAME.
     An unrecognized name sets the color to the default.  For
     information on what names are recognized, *note Color Names::..

`--frame-line-width FRAME_LINE_WIDTH'
     (Float, default -1.0.)  Set the width of lines in the plot frame,
     as a fraction of the width of the display, to FRAME_LINE_WIDTH.
     A negative value means that the default value for the line width
     provided by the `libplot' graphics library should be used.  This
     value is device-dependent.  The interpretation of zero line width
     is also device-dependent (on some devices, a zero-width line is the
     thinnest line that can be drawn; on others, a zero-width line is
     invisible).  `graph-tek' does not support drawing lines with other
     than a default width.

`--max-line-length MAX_LINE_LENGTH'
     (Integer, default 150.) Set the maximum length that the polygonal
     lines joining datasets are allowed to grow to, before they are
     flushed to the output device, to MAX_LINE_LENGTH.  Some display
     devices (e.g., old Postscript printers) cannot handle long
     polygonal lines, so that this option must be employed.

`--title-font-name TITLE_FONT_NAME'
     (String, default "Helvetica" except for `graph-tek', for which
     "HersheySerif" is the default.)  Set the font used for the plot
     title (`top label') to be FONT_NAME.  Normally the font used for
     the plot title is the same as that used for labelling the axes and
     the ticks along the axes, as specified by the `-F' option.  But the
     `--title-font-name' option may be used to override this.  Font
     names are case-insensitive; for a list of available fonts, *note
     Text Fonts::..  If the font is not available, the default font
     will be used.

`--title-font-size TITLE_FONT_SIZE'
     (Float, default 0.07.)  Set the size of the font for the top label
     (`title'), as specified by the `-L' option, to TITLE_FONT_SIZE.
     The size is expressed as a fraction of the size of the plotting
     box.

`--toggle-rotate-y-label'
     Position the label on the y axis (which is set with the `-Y'
     option) horizontally instead of vertically, or vice versa.  By
     default the label is rotated, so that it is positioned parallel to
     the y axis.  But some display devices (e.g., old X Window System
     displays) cannot handle rotated text.

`--toggle-switch-axis-end X|Y'
     Set the end of the indicated axis through which the other axis
     passes to be the opposite of what is currently the case.  E.g.,
     `--toggle-switch-axis-end x' will cause the y axis to appear on
     the right of the plot rather than the left.  (The left end is the
     default.)  Similarly, `--toggle-switch-axis-end y' will cause the
     x axis to appear at the top of the plot rather than the bottom.
     Note that if the x axis appears at the top, no plot title will be
     drawn (since there will be no room).


File: plotutils.info,  Node: Dataset Options,  Next: Multiplot Options,  Prev: Plot Options,  Up: graph Invocation

Dataset options
---------------

   The following options affect the way in which individual datasets are
read from files, and drawn as part of a plot.  They should appear on the
command line before the file containing the datasets whose reading or
rendering they will affect.  They may appear more than once on a command
line, if more than one file is to be read.

   The following three options affect the way in which datasets are read
from files.

`-I DATA-FORMAT'
`--input-format DATA-FORMAT'
     This specifies which format the subsequent input file(s) are in.

    `a'
          ASCII format.  Each input file consists of pairs of floating
          point numbers, interpreted as the x and y coordinates of the
          data points in a dataset.  The x and y coordinates of a point
          need not appear on the same line, and points need not appear
          on different lines.  But if a blank line occurs (i.e., two
          newlines in succession are seen), it is interpreted as the
          end of a dataset, and the beginning of the next.

    `d'
          Double precision binary format.  Each input file is a
          sequence of double precision floating point numbers,
          interpreted as forming pairs (x,y).  Successive datasets are
          separated by a single occurrence of the quantity `MAXDOUBLE',
          which is the largest possible double precision floating point
          number.  On most machines this is approximately 1.8x10^308.

    `e'
          ASCII format, including error bars.  Similar to `a' format,
          except that triples (x,y,error) appear instead of pairs (x,y).

    `g'
          The `table' format produced by the `gnuplot' plotting program.

`-a [STEP_SIZE [LOWER_LIMIT]]'
`--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]'
     (Floats, defaults 1.0 and 0.0.) Automatically generate abscissa
     (x) values.  Irrespective of data format (`a', `d', or `e'), this
     option specifies that the abscissa (x) values are missing: the
     dataset(s) to be read contain only ordinate (y) values.  The
     difference between successive x values will be STEP_SIZE, and the
     first x value will be LOWER_LIMIT.  To return to reading abscissa
     values from the input you may specify `-a 0', which disables
     automatic generation of the abscissa and returns STEP_SIZE and
     LOWER_LIMIT to their default values.

`-B'
`--toggle-auto-bump'
     By default the linemode (set with `-m', see below) is `bumped'
     (incremented by unity) at the beginning of each new dataset.  This
     option toggles auto-bumping: it turns it off if it was on, and on
     if it was off.

   The following options affect the way in which individual datasets are
drawn as part of a plot.  These options set the six `attributes' (symbol
type, symbol font, linemode, line width, fill fraction, and
color/monochrome) that each dataset has.

`-m LINE_MODE'
`--line-mode LINE_MODE'
     (Integer, default 1.) LINE_MODE specifies the mode (i.e., style)
     of the lines drawn between successive points in a dataset.  If the
     dataset is being rendered in monochrome, the interpretation of
     LINE_MODE is as follows.

       0. no line at all (points are disconnected)

       1. solid

       2. dotted

       3. dotdashed

       4. shortdashed

       5. longdashed

     Thereafter (i.e., for LINE_MODE greater than 5) the sequence of
     five linemodes repeats.  So besides linemode 0, there are a total
     of five distinct monochrome linemodes.  If the dataset is being
     rendered in color (as may be requested with the `-C' option), the
     interpretation of linemodes 0 through 5 is instead

       0. no line at all (points are disconnected)

       1. red, solid

       2. green, solid

       3. blue, solid

       4. magenta, solid

       5. cyan, solid

     Linemodes 6 through 10 use the same five colors, but are dotted;
     linemodes 11 through 15 are dotdashed; linemodes 16 through 20 are
     shortdashed; and linemodes 21 through 25 are longdashed.  So
     besides linemode 0, there are a total of 25 distinct colored
     linemodes.  A negative linemode indicates that no line should be
     drawn, but that the plotting symbol, if any (see below), should be
     in the color of the corresponding positive linemode.

`-S [SYMBOL_NUMBER [SYMBOL_SIZE]]'
`--symbol [SYMBOL_NUMBER [SYMBOL_SIZE]]'
     (Integer and float, defaults 0 and 0.03.) Draw a marker symbol at
     each data point.  SYMBOL_NUMBER specifies the symbol type, and
     SYMBOL_SIZE specifies the fractional size of the symbol with
     respect to the width of the plotting box.  If the dataset is being
     rendered in color, the symbol will have the color of the line that
     is being drawn to connect the data points.  You may request that
     symbols be drawn without any line connecting them by using the
     `-m' option to specify a negative linemode (see above).  The
     following table lists the first few marker symbols.

       0. no symbol at all

       1. dot

       2. plus (+)

       3. asterisk (*)

       4. circle

       5. cross

     Marker symbols 0 through 31 are furnished by the `libplot' graphics
     library.  *Note Marker Symbols::.  Symbol numbers greater than or
     equal to 32 are interpreted as characters to be selected from a
     symbol font, which may be set with the `--symbol-font-name' option
     (see below).

`-W LINE_WIDTH'
`--line-width LINE_WIDTH'
     (Float, default -1.0.)  Set the width of the lines used to join
     successive points in a dataset, as a fraction of the width of the
     display, to LINE_WIDTH.  A negative value means that the default
     value for the line width provided by the `libplot' graphics
     library should be used.  This value is device-dependent.  The
     interpretation of zero line width is also device-dependent (on some
     devices, a zero-width line is the thinnest line that can be drawn;
     on others, a zero-width line is invisible).  `graph-tek' does not
     support drawing lines with other than a default width.

`-q FILL_FRACTION'
`--fill-fraction FILL_FRACTION'
     (Float, default -1.0.)  If successive points in a dataset are
     joined by line segments, set the shading intensity for the polygon
     formed by the line segments to be FILL_FRACTION.  A solid polygon
     (i.e., one filled with the `pen color' used for drawing the line
     segments) is obtained by choosing FILL_FRACTION=1.0.  The interior
     of the polygon will be white if FILL_FRACTION=0.0.  The polygon
     will be unfilled (transparent) if FILL_FRACTION is negative.
     If the polygon intersects itself, the `even-odd rule' will be used
     to determine which points are inside and outside, i.e., to
     determine which portions of the polygon should be shaded.  The
     even-odd rule is explained in the `Postscript Language Reference
     Manual'.  In `graph-tek', the `-q' option has no effect.

`-C'
`--toggle-use-color'
     Toggle between color and monochrome rendering of datasets.  The
     interpretation of linemode depends on whether the rendering is
     being performed in color or monochrome; see the `-m' option above.

`--symbol-font-name SYMBOL_FONT_NAME'
     (String, default "ZapfDingbats" for all versions of `graph' except
     for `graph-tek', for which it is "HersheySerif".)  Set the symbol
     font, from which plotting symbols numbered 32 and higher are
     selected, to be SYMBOL_FONT_NAME.  Font names are case-insensitive.
     For a list of available fonts, *note Text Fonts::..


File: plotutils.info,  Node: Multiplot Options,  Next: Raw graph Options,  Prev: Dataset Options,  Up: graph Invocation

Multiplot options
-----------------

   The following options are used for multiplotting (placing several
plots on a display, or a page, at once).

`--reposition X Y SIZE'
     (Floats, defaults 0.0, 0.0, 1.0.)  Set the `virtual display' within
     which the next plot will be drawn to be a square of size SIZE,
     with lower left corner (X,Y).  This is in the coordinate frame in
     which the physical display is a unit square with lower left corner
     (0,0).

`--blankout BLANKOUT_FRACTION'
     (Float, default 1.3.)  When drawing each additional plot of a
     multiplot, it is desirable to clear the region of the display on
     which the plot will be drawn.  If BLANKOUT_FRACTION=1.0, the
     region covered by the plot's plotting box will be cleared.  If
     BLANKOUT_FRACTION=1.3, a region 30% larger in each dimension will
     be cleared.  This is appropriate for inset plots; 1.0 would be
     appropriate for side by side plots.  Note that `graph-tek' does not
     know how to clear regions.


File: plotutils.info,  Node: Raw graph Options,  Next: Info Options,  Prev: Multiplot Options,  Up: graph Invocation

Raw `graph' options
-------------------

   The following options are meaningful for raw `graph' only.  They
should appear on the command line before any filenames, since they
affect the output of the plot (or multiplot) as a whole.

`-O'
`--ascii-output'
     Output the portable (ASCII) version of GNU metafile format, rather
     than a binary version (the default).

`-h'
`--high-byte-first'
`-l'
`--low-byte-first'
     These options force `graph' to use the specified byte order when
     writing out a file in the binary version of GNU metafile format.
     By default the byte order is host-dependent.


File: plotutils.info,  Node: Info Options,  Prev: Raw graph Options,  Up: graph Invocation

Informational options
---------------------

   The following options request information.

`--help'
     Print a list of command-line options, and then exit.

`--help-fonts'
     Print a list of available fonts, and then exit.  The list will
     depend on which version of `graph' is being used.  `graph-X',
     `graph-ps', and `graph-fig' each support the 35 standard
     Postscript fonts.  All three, and `graph-tek', support a set of 16
     Hershey vector fonts.  Raw `graph' in principle supports any font,
     since its output must be translated to other formats with `plot'.

`--version'
     Print the version of `graph' and the plotting utilities package,
     and exit.


File: plotutils.info,  Node: Plot Filters,  Next: libplot,  Prev: graph Invocation,  Up: Top

The Plot Filters
****************

* Menu:

* Plot Filter Invocation::	How to use a plot filter
* Plot Filter Options::		Command-line options


File: plotutils.info,  Node: Plot Filter Invocation,  Next: Plot Filter Options,  Prev: Plot Filters,  Up: Plot Filters

Examples of the use of a plot filter
====================================

   The GNU plot filters (`plot2X', `plot2ps', `plot2fig', `plot2tek',
and `plot2plot', collectively called `plot'), translate GNU graphics
metafiles to other formats.  Graphics metafiles are produced by raw
`graph' and by raw `libplot'.  The metafile format is a
device-independent format for storage of graphic data.  By default, it
is a binary rather than an ASCII format (*note Metafiles::.).

   The plot filters, like raw `graph' and the metafile format itself,
are useful if you wish to preserve a plot that is to be displayed or
edited on more than one type of display device.  The following
illustrate how this is done.

   To produce a plot of data arranged as alternating x and y
coordinates in an ASCII file, you may use raw `graph' as follows:

     graph < ascii_data_file > test.plot

The file `test.plot' will be a GNU graphics metafile.  Similarly, to
create a plot consisting of a simple figure, you may do:

     echo 0 0 1 1 2 0 | spline | graph > test.plot

To display any such plot on an X Window System display, you would do

     plot2X < test.plot

To print the plot on a Postscript printer, you would do something like

     plot2ps < test.plot | lpr

To edit the plot with the `idraw' drawing editor, you would do

     plot2ps < test.plot > test.ps
     idraw test.ps

And to edit it with the `xfig' drawing editor, you would do

     plot2fig < test.plot > test.fig
     xfig test.fig

   Of the five versions of `plot', `plot2tek' and `plot2X' may behave
differently depending on the environment in which they are invoked.
This refers to the values taken by the `TERM' and `DISPLAY' environment
variables, in particular.  For a discussion of the effects of the
environment on `plot2tek' and `plot2X', *note Environment::..


File: plotutils.info,  Node: Plot Filter Options,  Prev: Plot Filter Invocation,  Up: Plot Filters

Plot filter command-line options
================================

   The command-line options to the plot filters (`plot2X', `plot2ps',
`plot2fig', `plot2tek', and `plot2plot', collectively called `plot')
are listed below.  There are four sorts of option:

  1. Options specifying the type of GNU metafile format the input is in.

  2. Options meaningful only for `plot2plot', which outputs GNU metafile
     format.

  3. Options setting initial values of drawing parameters.

  4. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the
type and default value of the argument.

   Note that input file names may be specified anywhere on the command
line.  Only the options that precede a file name will take effect for
that file.  If no file names are specified, or the name `-' is
specified, the standard input is read.

   The following options specify the type of GNU metafile format the
input is in.  There are actually two types of GNU metafile format:
portable (ASCII) and binary (the default).  The binary format is
machine-dependent; it depends on the byte order of the unformatted,
signed, two-byte integer coordinates contained in plot commands.  The
`-h' and `-l' options specify this order explicitly.  If the order is
not specified, the plot filters attempt to determine the byte order
from commands early in the metafile, but the method is heuristic and
not foolproof.

`-I'
`--ascii-input'
     Specifies that the input is in the portable (ASCII) version of GNU
     metafile format, rather than a binary version (the default).  The
     portable version is produced by raw `graph' when the `-O' option
     is used.

`-h'
`--high-byte-first'
     This option specifies that the high-order byte of each signed,
     two-byte integer occurs first in the metafile.  It disables
     determination of byte order from the metafile itself.

`-l'
`--low-byte-first'
     This option specifies that the low-order byte of each signed,
     two-byte integer occurs first in the metafile.  It disables
     determination of byte order from the metafile itself.

   The following option is meaningful only for `plot2plot', which
outputs a graphics metafile.

`-O'
`--ascii-output'
     Output the portable (ASCII) version of GNU metafile format, rather
     than a binary version (the default).

   The following options set the initial values of drawing parameters.
These parameters may be overridden by directives in the metafile itself.
In fact these options are useful mostly for old metafiles in the
pre-GNU `plot(5)' format, which did not include such directives.

`-f FONT_SIZE'
`--font-size FONT_SIZE'
     (Float, default 0.0525.)  Set the initial size of the font used
     for rendering text, as a fraction of the width of the display
     device, to FONT_SIZE.

`-F FONT_NAME'
`--font-name FONT_NAME'
     (String, default "Helvetica" except for `graph-tek', for which
     "HersheySerif" is the default.)  Set the font initially used for
     text (i.e., for `labels') to FONT_NAME.  Font names are
     case-insensitive.  For a list of available fonts, *note Text
     Fonts::..

`-W LINE_WIDTH'
`--line-width LINE_WIDTH'
     (Float, default -1.0.)  Set the width of lines, as a fraction of
     the width of the display, to LINE_WIDTH.  A negative value means
     that the default value provided by the `libplot' graphics library
     should be used.  This value is device-dependent.  The
     interpretation of zero line width is also device-dependent (on some
     devices, a zero-width line is the thinnest line that can be drawn;
     on others, a zero-width line is invisible).  `plot2tek' does not
     support drawing lines with other than a default width.

`--pen-color NAME'
     (String, default "black".)  Set the pen color to be NAME.  An
     unrecognized name sets the pen color to the default.  For
     information on what color names are recognized, *note Color
     Names::..

   The following options request information.

`--help'
     Print a list of command-line options, and then exit.

`--help-fonts'
     Print a list of available fonts, and then exit.  The list will
     depend on which version of `plot' is being used.  `plot2X',
     `plot2ps', and `plot2fig' each support the 35 standard Postscript
     fonts.  All three, and `plot2tek', support a set of 16 Hershey
     vector fonts.  `plot2plot' in principle supports any font, since
     its output must be translated to other formats by a later
     invocation of `plot'.

`--version'
     Print the version of `plot' and the plotting utilities package, and
     exit.


File: plotutils.info,  Node: libplot,  Next: spline Examples,  Prev: Plot Filters,  Up: Top

`libplot', a Function Library
*****************************

   GNU `libplot' is a library of functions for device-independent
two-dimensional vector graphics.  There are functions for drawing lines,
open and closed polylines, arcs (both circular and elliptic), circles
and ellipses, markers, and text strings.  The filling of objects other
than text strings is supported (fill color, as well as pen color, may
be set arbitrarily).

   There are five versions of `libplot', which differ in the display
device they produce output for.

   * `libplotX'.  This version pops up a window on an X Window System
     display, and draws the graphics in it.  (The window will close if
     you type `q' or click your mouse in it.)

   * `libplotps'. This version produces Postscript output.  It is in EPS
     (encapsulated Postscript) format, so it may be included in another
     document.  The output may be edited with the `idraw' drawing
     editor.

   * `libplotfig'.  This version produces output in Fig format, which
     may be edited with the `xfig' drawing editor.  The `xfig' editor
     will export drawings in various other formats for inclusion in
     documents.

   * `libplottek'.  This version produces output in Tektronix 4014
     format, which may be displayed on any Tektronix 4014 emulator.
     Such an emulator is built into `xterm', the X Window System
     terminal emulation program.  The DOS version of `kermit' also
     includes such an emulator.

   * Raw `libplot'.  This version produces output in GNU metafile
     format, which is an extended version of the `plot(5)' format found
     on some other operating systems.  It may be translated to other
     formats with the GNU plot filters.  (*Note Plot Filters::.)

   The functions in these libraries behave identically, so far as the
caller knows.  So a given graphics application may be linked with any of
them, and will still function.  There are a handful of external
variables that distinguish among the libraries, but the casual
programmer does not need to know about them.

   Of the libraries, `libplotX', `libplottek', and raw `libplot' are
real-time.  This means that graphics are drawn, or written to a file,
as the graphics functions are called.  `libplotps' and `libplotfig' are
not real-time, since their output files can only be constructed after
all functions have been called.  For `libplotps' this is because the
output file must contain a `bounding box' line.  For `libplotfig' it is
because definitions of nonstandard colors, if any, must be placed at the
head of the output file.

   By convention the physical `graphics display' drawn in by each of the
libraries is square.  For example, `libplotX' pops up a square window
and draws graphics in it.  Actually, the programmer specifies the
coordinates of graphical objects in a `user frame', which is not the
same as the device frame.  The two frames are related by an arbitrary,
user-specifiable, affine coordinate transformation.

* Menu:

* Programming::		Programming with libplot: An overview
* Functions::		A list of functions contained in libplot
* Environment::		Environment variables and X resources


File: plotutils.info,  Node: Programming,  Next: Functions,  Prev: libplot,  Up: libplot

Programming with `libplot'
==========================

   The source code for any graphics application that calls `libplot'
functions, if written in C, should contain the lines

     #include <stdio.h>
     #include <plot.h>

The header file `plot.h' is distributed with `libplot', and should have
been installed on your system where your C compiler will find it.
It contains prototypes for each of the functions in `libplot' and some
miscellaneous definitions.  It may be used with C++ programs as well as
C programs.

   To link your application with any of the versions of `libplot', you
would use the appropriate `-l' option(s) on the command line when
compiling it.  For example, you would use `-lplotps -lm' to link with
`libplotps', `-lplotfig -lm' to link with `libplotfig', and `-lplottek
-lm' to link with `libplottek'.  To link with `libplotX', you would use

     -lplotX -lXaw -lXmu -lXt -lX11 -lm

(or perhaps `-lplotX -lXm -lXt -lX11 -lm', `-lplotX -lXm -lXt -lX11 -lm
-lc -lgen', or `-lplotX -lXm -lXt -lX11 -lm -lc -lPW', on systems that
provide Motif widgets instead of Athena widgets).  To link with raw
`libplot', you would simply use `-lplot'.

   Before drawing any objects or calling any of the other `libplot'
functions, your application should call the `libplot' function
`openpl'.  Before exiting, and after all other `libplot' calls, it
should call `closepl'.  A given application may contain any number of
`openpl'...`closepl' pairs.

   By default, applications linked with versions of `libplot' other
than `libplotX' write graphics to standard output. The output stream to
which plotting commands are directed, in versions other than
`libplotX', may be set by calling `outfile'.  The `outfile' function
may only be called outside an `openpl'...`closepl' pair.

   In non-GNU versions of `libplot', an application is expected to call
the `space' function immediately after calling `openpl', to set the
rectangular region (in user coordinates) that will be mapped to the
graphics display (by convention, square).  GNU `libplot' includes
`space', and also an extended version (`space2'), which allows the user
to specify a parallelogram-shaped region rather than a rectangular
region.  So an arbitrary affine transformation from the user frame to
the device frame may be specified, immediately after calling `openpl'.
This affine transformation may be updated, if desired, by calling
`fconcat'.  The `fconcat' function will `concatenate' (i.e., compose)
this transformation with any specified affine map.  This sort of
concatenation is a capability familiar from, for example, Postscript.

   GNU `libplot' also provides an application with the ability to
maintain a Postscript-style stack of drawing states, i.e., graphics
contexts.  A drawing state includes such modal drawing attributes as
graphics cursor position, line mode, line width, pen and fill colors,
and the font used for drawing text.  It also includes the current affine
map from user to device coordinates.  The state of any uncompleted
polyline object (if any) is included as well, since polylines may be
drawn incrementally, one line segment at a time.  The current drawing
state may be pushed onto the stack of drawing states by calling
`savestate', and popped off by calling `restorestate'.


File: plotutils.info,  Node: Functions,  Next: Environment,  Prev: Programming,  Up: libplot

The functions in `libplot': A detailed listing
==============================================

   The functions in GNU `libplot' are subdivided into the four sets
tabulated below.

   Note that many functions come in two versions: integer and double
precision floating point.  Internally, `libplot' uses double precision
floating point.  The integer versions are provided for backward
compatibility.  If there are two versions of a function, the name of
the floating point version begins with the letter `f'.

   Many functions come in both absolute and relative versions, also.
The latter use relative coordinates (i.e., coordinates relative to the
current position of the graphics cursor), and their names end in `rel'.

   Currently, only a few functions have meaningful return values.

* Menu:

* Setup Functions::	Functions that initialize and close the display device
* Attribute Functions::	Functions that affect drawing attributes
* Drawing Functions::	Functions that draw objects
* Mapping Functions::	Functions affecting the user -> device coordinate map


File: plotutils.info,  Node: Setup Functions,  Next: Attribute Functions,  Prev: Functions,  Up: Functions

Setup functions
---------------

FILE *outfile (FILE *FP);
     outfile, which must be called outside a openpl...closepl pair,
     directs all graphics output to the stream (i.e., open file) FP.
     The previous output stream is returned.  The default output stream
     is stdout.  outfile has no effect in `libplotX', which draws
     graphics directly on an X Window System display.

int openpl ();
     openpl opens the display device.  Depending on the version of
     `libplot', it may write initialization commands to the output
     stream.

int erase ();
     erase is called to erase all objects from the graphics display,
     e.g., before a new plot is drawn.  This is important only for
     `libplottek' and raw `libplot'.

int space (int X0, int Y0, int X1, int Y1);
int fspace (double X0, double Y0, double X1, double Y1);
     space and fspace take two pairs of arguments, specifying the
     positions of the lower left corner and upper right corner of the
     display device, in user coordinates.  In other words, calling
     space or fspace sets the affine transformation from user
     coordinates to device coordinates.

int space2 (int X0, int Y0, int X1, int Y1, int X2, int Y2);
int fspace2 (double X0, double Y0, double X1, double Y1, double X2, double Y2);
     space2 and fspace2 are extended versions of space and fspace.
     Their arguments are the three defining vertices of an `affine
     window' (a drawing parallelogram), in user coordinates.  The
     specified vertices are the lower left, the lower right, and the
     upper left.  This window will be mapped affinely onto the display
     device.

int closepl ();
     closepl closes the display device.  In versions of `libplot' that
     do not do real-time plotting (i.e., `libplotps' and `libplotfig'),
     it writes the plotted objects to the output stream.


File: plotutils.info,  Node: Attribute Functions,  Next: Drawing Functions,  Prev: Setup Functions,  Up: Functions

Attribute-setting functions
---------------------------

   The following are the `libplot' functions that set drawing
attributes, or save and restore them.

int capmod (char *S);
     capmod sets the cap mode for all polylines subsequently drawn on
     the graphics display (by repeated calls to cont or fcont).
     Recognized modes are "butt" (the default), "round", and
     "projecting".  This function has no effect in `libplottek' or
     (currently) in `libplotps'.

int color (int RED, int GREEN, int BLUE);
     color is a convenience function.  Calling color is equivalent to
     calling both pencolor and fillcolor, to set both the the pen color
     and fill color of all objects subsequently drawn on the graphics
     display.

int colorname (char *NAME);
     colorname is a convenience function.  Calling colorname is
     equivalent to calling both pencolorname and fillcolorname, to set
     both the the pen color and fill color of all objects subsequently
     drawn on the graphics display.

int fill (int LEVEL);
     fill sets the fill fraction for all subsequently drawn objects.
     A value of 0 for LEVEL indicates that objects should be unfilled,
     or transparent.  This is the default.  A value in the range
     0x0001...0xffff, i.e., 1...65535, indicates that objects should be
     filled.  A value of 1 signifies 100% filling (the fill color will
     simply be the color specified by calling fillcolor or
     fillcolorname).  If LEVEL=0xffff, the fill color will be white.
     Values between 0x0001 and 0xffff are interpreted as specifying a
     desaturation, or gray level.  0x8000 specifies 50% filling (the
     fill color will be intermediate between the color specified by
     calling fillcolor or fillcolorname, and white).  `libplottek' does
     not support filling.

     If the object to be filled is a self-intersecting polyline, the
     `even-odd rule' will be applied to determine which points are
     inside, i.e., which of the regions bounded by the polyline should
     be filled.  The even-odd rule is explained in the `Postscript
     Language Reference Manual'.

int fillcolor (int RED, int GREEN, int BLUE);
     fillcolor sets the fill color of all objects subsequently drawn on
     the graphics display, using a 48-bit RGB color model.  The
     arguments RED, GREEN and BLUE specify the red, green and blue
     intensities of the fill color.  Each is an integer in the range
     0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies
     black, and the choice (65535, 65535, 65535) signifies white.  Note
     that the physical fill color depends also on the fill fraction,
     which is specified by calling fill.  `libplottek' does not support
     filling.

int fillcolorname (char *NAME);
     fillcolorname sets the fill color of all objects subsequently drawn
     on the graphics display to be NAME.  For information on what color
     names are recognized, *note Color Names::..  Unrecognized colors
     are interpreted as "black".  Note that the physical fill color
     depends also on the fill fraction, which is specified by calling
     fill.  `libplottek' does not support filling.

int fontname (char *FONT_NAME);
double ffontname (char *FONT_NAME);
     fontname and ffontname take a single case-insensitive string
     argument, FONT_NAME, specifying the name of the font to be used
     for all text strings subsequently drawn on the display device.
     (The font for plotting strings is fully specified by calling
     fontname, fontsize, and textangle.)  The default font name depends
     on the version of `libplot'.  It is "Helvetica" for all versions
     except `libplottek', for which it is "HersheySerif".  If the
     argument FONT_NAME is NULL or the font is not available, the
     default font name will be used.  Which fonts are available also
     depends on the version of `libplot'; for a list of available
     fonts, *note Text Fonts::..  The size of the font in user
     coordinates is returned, except in raw `libplot', in which the
     return value is currently zero.

int fontsize (int SIZE);
double ffontsize (double SIZE);
     fontsize and ffontsize take a single argument, interpreted as the
     size, in the user frame, of the font to be used for all text
     strings subsequently drawn on the display device.  (The font for
     plotting strings is fully specified by calling fontname, fontsize,
     and textangle.)  The size of the font in user coordinates is
     returned, except in raw `libplot', in which the return value is
     currently zero.  A negative value for SIZE sets the size to a
     default value, which is device-dependent.

int joinmod (char *S);
     joinmod sets the join mode for all polylines subsequently drawn on
     the graphics display (by repeated calls to cont or fcont).
     Recognized modes are "miter" (the default), "round", and "bevel".
     This function has no effect in `libplottek' or (currently) in
     `libplotps'.

int linemod (char *S);
     linemod takes a single string argument S containing the name of
     the linemode (i.e., line style) desired.  The names supported are
     "disconnected", "solid", "dotted", "dotdashed", "shortdashed", and
     "longdashed".  A `disconnected' polyline joining a sequence of
     points is invisible, though the points themselves are visible.
     Disconnected polylines are never filled. The other five linemodes
     correspond more or less to the following bit patterns:

          "solid"             --------------------------------
          "dotted"            - - - - - - - - - - - - - - - -
          "dotdashed"         -----------  -  -----------  -
          "shortdashed"       --              --
          "longdashed"        -------         -------

int linewidth (int size);
int flinewidth (double size);
     linewidth and flinewidth set the width, in the user frame, of all
     lines, polylines, arcs, circles, and ellipses subsequently drawn on
     the graphics display.  A negative value means that a default width
     should be used.  This default width is device-dependent.  The
     interpretation of zero line width is also device-dependent (on some
     devices, a zero-width line is the thinnest line that can be drawn;
     on others, a zero-width line is invisible).  `libplottek' does not
     support drawing with other than a default width.

int pencolor (int RED, int GREEN, int BLUE);
     pencolor sets the pen color of all objects subsequently drawn on
     the graphics display, using a 48-bit RGB color model.  The
     arguments RED, GREEN and BLUE specify the red, green and blue
     intensities of the pen color.  Each is an integer in the range
     0x0000...0xffff, i.e., 0...65535.  The choice (0, 0, 0) signifies
     black, and the choice (65535, 65535, 65535) signifies white.

int pencolorname (char *NAME);
     pencolorname sets the pen color of all objects subsequently drawn
     on the graphics display to be NAME.  For information on what color
     names are recognized, *note Color Names::..  Unrecognized colors
     are interpreted as "black".

int restorestate ();
     restorestate pops the current drawing state off the stack of
     drawing states.  The drawing state consists largely of `libplot''s
     drawing parameters, which are set by the `attribute functions'.
     So popping off the drawing state restores the drawing parameters
     to values they previously had.  The state of an uncompleted
     polyline object, if any, is regarded as part of the drawing state.
     For this reason, calling restorestate automatically calls endpoly
     to terminate the polyline under construction.

int savestate ();
     savestate pushes the current drawing state onto the stack of
     drawing states.  The drawing state consists largely of `libplot''s
     drawing parameters, which are set by the `attribute functions'.
     The state of an uncompleted polyline object, if any, is regarded
     as part of the drawing state.  That is because polylines may be
     drawn incrementally, one line segment at a time.  When a drawing
     state is returned to, the polyline in progress may be continued.

int textangle (int ANGLE);
double ftextangle (double ANGLE);
     textangle and ftextangle take one argument, which specifies the
     angle in degrees counterclockwise from the x (horizontal) axis in
     the user frame, for the text strings subsequently drawn on the
     display device.  The default angle is zero.  (The font for
     plotting strings is fully specified by calling fontname, fontsize,
     and textangle.)  The size of the font for plotting strings, in user
     coordinates, is returned, except in raw `libplot', in which the
     return value is currently zero.


File: plotutils.info,  Node: Drawing Functions,  Next: Mapping Functions,  Prev: Attribute Functions,  Up: Functions

Object-drawing functions
------------------------

   The following are the `libplot' functions that draw objects (lines,
open and closed polylines, points, arcs, circles, ellipses, marker
symbols, and text) on a graphics display.

int alabel (int HORIZ_JUSTIFY, int VERT_JUSTIFY, char *S);
double falabel (int HORIZ_JUSTIFY, int VERT_JUSTIFY, char *S);
     alabel and falabel take three arguments HORIZ_JUSTIFY,
     VERT_JUSTIFY, and S, and plot the text string S as an `adjusted
     label', i.e., according to the adjustments specified in
     HORIZ_JUSTIFY and VERT_JUSTIFY.  HORIZ_JUSTIFY is equal to `l',
     `c', or `r' for left, center or right justification, relative to
     the current graphics cursor position.  VERT_JUSTIFY is equal to
     `b', `x', `c', or `t' for placing the bottom, baseline, center or
     top of the string even with the graphics cursor position.  The
     cursor position is moved to the right end of the string if left
     justification is specified, and to the left end if right
     justification is specified.  The string may be plotted at a
     nonzero angle, if `textangle' has been called.  The string may
     contain escape sequences of various sorts (*note Text String
     Format::.), though it should not contain line feeds or carriage
     returns.  In fact it should include only printable characters,
     from the byte ranges 0x20...0x7e and 0xa0...0xff.  The width of the
     string in user coordinates is returned, except in raw `libplot', in
     which the return value is currently zero.

int arc (int X, int Y, int X0, int Y0, int X1, int Y1);
int farc (double X, double Y, double X0, double Y0, double X1, double Y1);
int arcrel (int X, int Y, int X0, int Y0, int X1, int Y1);
int farcrel (double X, double Y, double X0, double Y0, double X1, double Y1);
     arc and farc take six arguments specifying the coordinates of the
     center (X, Y), beginning (X0, Y0), and end (X1, Y1) of a circular
     arc.  The graphics cursor location becomes (X, Y).  arcrel and
     farcrel are similar to `arc' and `farc', but use cursor-relative
     coordinates.

int box (int X1, int y1, int X2, int Y2);
int fbox (double X1, double Y1, double X2, double Y2);
int boxrel (int X1, int y1, int X2, int Y2);
int fboxrel (double X1, double y1, double X2, double Y2);
     box and fbox take four arguments specifying the lower left corner
     (X1, Y1) and upper right corner (X2, Y2) points of a `box', or
     rectangle.  The graphics cursor is moved to (X2, Y2).  boxrel and
     fboxrel are similar to box and fbox, but use cursor-relative
     coordinates.

int circle (int X, int Y, int R);
int fcircle (double X, double Y, double R);
int circlerel (int X, int Y, int R);
int fcirclerel (double X, double Y, double R);
     circle and fcircle take three arguments specifying the center (X,
     Y) of an circle and its radius (R).  The graphics cursor is moved
     to (X, Y).  circlerel and fcirclerel are similar to circle and
     fcircle, but use cursor-relative coordinates for X and Y.

int cont (int X, int Y);
int fcont (double X, double Y);
int contrel (int X, int Y);
int fcontrel (double X, double Y);
     cont and fcont take two arguments specifying the coordinate (X, Y)
     for the continuation of a line.  This draws a line segment from
     the current graphics cursor position to the point (X, Y).  The
     graphics cursor is moved to (X, Y).  A polyline comprising an
     arbitrary number of line segments may be drawn by repeated calls
     to cont or fcont.  The polyline may be terminated by calling
     endpoly.  Polylines are also terminated if any other object is
     drawn or any drawing attribute is set.  To produce a closed
     polyline rather than an open one, the final point should be the
     same as the first point.  contrel and fcontrel are similar to cont
     and fcont, but use cursor-relative coordinates.

int ellarc (int xc, int yc, int x0, int y0, int x1, int y1);
int fellarc (double xc, double yc, double x0, double y0, double x1, double y1);
int ellarcrel (int xc, int yc, int x0, int y0, int x1, int y1);
int fellarcrel (double xc, double yc, double x0, double y0, double x1, double y1);
     ellarc and fellarc take six arguments specifying the three points
     `pc'=(XC,YC), `p0'=(X0,Y0), and `p1'=(X1,Y1) that define a
     so-called quarter ellipse.  This is an elliptic arc with center
     `pc', extending from `p0' to `p1', which is an affinely
     transformed version of a quarter circle.  It is constructed as
     follows.  If the cross product (`p0'-`pc')x(`p1'-`pc') is
     positive, the elliptic arc is chosen to have control points `p0',
     `p1', and `p0'+`p1'-`pc'.  This means that it is tangent at `p0'
     to the line segment joining `p0' to `p0'+`p1'-`pc', and is tangent
     at `p1' to the line segment joining `p1' to `p0'+`p1'-`pc'.  So it
     fits snugly into a triangle with these three control points as
     vertices.  If on the other hand the cross product is negative, a
     so-called three-quarter ellipse is drawn instead.  ellarcrel and
     fellarcrel are similar to ellarc and fellarc, but use
     cursor-relative coordinates.

int ellipse (int x, int y, int rx, int ry, int angle);
int fellipse (double x, double y, double rx, double ry, double angle);
int ellipserel (int x, int y, int rx, int ry, int angle);
int fellipserel (double x, double y, double rx, double ry, double angle);
     ellipse and fellipse take five arguments specifying the center (X,
     Y) of an an ellipse, the lengths of its semiaxes (RX and RY), and
     the inclination of the first semiaxis in the counterclockwise
     direction from the x axis in the user frame.  ellipserel and
     fellipserel are similar to ellipse and fellipse, but use
     cursor-relative coordinates.

int endpoly ();
     endpoly terminates the polyline under construction, if any.
     Polylines, which are formed by repeated calls to cont or fcont,
     are also terminated if any other object is drawn or any drawing
     attribute is set.  So endpoly is almost redundant.  However, in
     versions of `libplot' that plot objects in real time, calling
     endpoly will ensure that the polyline is drawn on the graphics
     display without delay.

int label (char *S);
     label takes a single string argument S and draws the text
     contained in S at the current graphics cursor position.  The text
     is left justified, and the graphics cursor is moved to the right
     end of the string.  This function is provided for backward
     compatibility; the function call label(S) is equivalent to
     alabel(`l',`x',S).

int labelwidth (char *S);
double flabelwidth (char *S);
     labelwidth and flabelwidth compute and return the width of a
     string in the current font, in the user frame.  The return value is
     the same as what is returned by alabel or falabel, but the string
     is not actually plotted.  In raw `libplot', this function
     currently returns zero.

int line (int X1, int Y1, int X2, int Y2);
int fline (double X1, double y1, double X2, double Y2);
int linerel (int X1, int y1, int X2, int Y2);
int flinerel (double X1, double y1, double X2, double Y2);
     line and fline take four arguments specifying the start point (X1,
     Y1) and end point (X2, Y2) of a line.  The graphics cursor is
     moved to (X2, Y2).  These are convenience functions, since line
     (X1, Y1, X2, Y2) is equivalent to move (X1, Y1) followed by cont
     (X2, Y2).  The line may be extended to a polyline by further calls
     to cont or fcont.  linerel and flinerel are similar to line and
     fline, but use cursor-relative coordinates.

int marker (int x, int y, int type, int size);
int fmarker (double x, double y, int type, double size);
int markerrel (int x, int y, int type, int size);
int fmarkerrel (double x, double y, int type, double size);
     marker and fmarker take four arguments specifying the location
     (x,y) where a marker symbol is to be plotted, its type, and its
     size in user coordinates.  The graphics cursor moves to (x,y).
     Marker symbol types 0 through 31 are the same for all versions of
     `libplot', and marker symbol types 32 and above are interpreted as
     the index of a character in the current text font.  *Note Marker
     Symbols::.  markerrel and fmarkerrel are similar to marker and
     fmarker, but use cursor-relative coordinates for the position
     (x,y).

int move (int X, int Y);
int fmove (double X, double Y);
int moverel (int X, int Y);
int fmoverel (double X, double Y);
     move and fmove take two arguments specifying the coordinates (X,
     Y) of the new graphics cursor position.  This is equivalent to
     lifting the pen on a plotter and moving it to a new position,
     without drawing any line.  moverel and fmoverel are similar to
     move and fmove, but use cursor-relative coordinates.

int point (int X, int Y);
int fpoint (double X, double Y);
int pointrel (int X, int Y);
int fpointrel (double X, double Y);
     point and fpoint take two arguments specifying the coordinate (X,
     Y) for a single point.  The graphics cursor is moved to (X, Y),
     and a point is plotted.  pointrel and fpointrel are similar to
     point and fpoint, but use cursor-relative coordinates.


File: plotutils.info,  Node: Mapping Functions,  Prev: Drawing Functions,  Up: Functions

Mapping functions
-----------------

   The following four `libplot' functions affect the affine map from
the user frame to the device frame.  They may be viewed as performing
transformations of the user frame.  Their names resemble those of the
corresponding functions in the Postscript language.  For information on
how to use them to draw graphics efficiently, consult any good book on
Postscript programming, or the `Postscript Language Reference Manual'.

int fconcat (double M0, double M1, double M2, double M3, double TX, double TY);
     Apply a Postscript-style transformation matrix, i.e., affine map,
     to the user coordinate system.  That is, apply the linear
     transformation defined by the two by two matrix [M0 M1 M2 M3] to
     the user coordinate system, and also translate by TX units in the
     x direction and TY units in the y direction, relative to the
     former user coordinate system.  The following three functions
     (frotate, fscale, ftranslate) are convenience functions that are
     special cases of fconcat.

int frotate (double THETA);
     Rotate the user coordinate system axes about their origin by THETA
     degrees, with respect to their former orientation.  The position
     of the user coordinate origin and the size of the x and y units
     remain unchanged.

int fscale (double SX, double SY);
     Make the x and y units in the user coordinate system be the size
     of SX and SY units in the former user coordinate system.  The
     position of the user coordinate origin and the orientation of the
     coordinate axes are unchanged.

int ftranslate (double TX, double TY);
     Move the origin of the user coordinate system by TX units in the
     x direction and TY units in the y direction, relative to the
     former user coordinate system.  The size of the x and y units and
     the orientation of the coordinate axes are unchanged.


File: plotutils.info,  Node: Environment,  Prev: Functions,  Up: libplot

Environment variables and X Window System resources
===================================================

   The way in which `libplot' draws graphics is affected by several
environment variables.  In consequence, the behavior of `graph',
`plot', and other applications based on `libplot' are affected.
In particular, this is the case with `graph-tek' and `graph-X', and
`plot2tek' and `plot2X'.

   `libplottek', which produces output for a Tektronix terminal or
emulator, checks the `TERM' environment variable when the `openpl'
function is called to initialize the output device.  If the value of
this variable is `xterm', `xterms', or `kterm', it is taken as a sign
that the current application is running in an X Window System VT100
terminal emulator: an `xterm'.  Before producing output in Tektronix
format, `libplottek' will issue an escape sequence which causes the
terminal emulator's auxiliary Tektronix window, which is normally
hidden, to pop up.  When the `closepl' function is called to end the
drawing, it will issue an escape sequence which returns control to the
original VT100 window.  The Tektronix window will remain on the screen.

   If the value of `TERM' is `kermit', `ansi.sys', `ansissys',
`ansi.sysk', or `ansisysk', it is taken as a sign that the current
application is running in the Tektronix emulator provided by a DOS
version of `kermit'.  If so, some of the Tektronix control codes output
by `libplottek' will be `kermit'-specific.  There will be a limited
amount of color support (the 16 `ansi.sys' colors will be supported).
Unless it believes it is running in a `kermit' Tektronix emulator,
`libplottek' will not use color.

   `libplotX', which pops up a window on an X Window System display and
draws graphics in it, is similarly affected by the environment in which
it runs.  The environment variable `DISPLAY' determines the display on
which it will pop up the window.  `libplotX' also looks at the
X resource `Xplot.geometry'.  It will use the value of this resource,
which may be set by the user, as the size of the window in terms of
pixels.  The default value is "570x570".

   The functioning of the other versions of `libplot', namely
`libplotfig', `libplotps', and raw `libplot', is not affected by the
environment.


File: plotutils.info,  Node: spline Examples,  Next: spline Invocation,  Prev: libplot,  Up: Top

The `spline' Utility
********************

An introduction to `spline'
===========================

   GNU `spline' is a program for interpolating between the data points
in one or more datasets.  The simplest case is when there is only a
single dataset, in ASCII format.  The dataset would consist of
alternating x and y coordinates.  For example, the input file could
contain the lines

     0.0  0.0
     1.0  1.0
     2.0  0.0

which are the coordinates of the data points (0,0), (1,1), and (2,0).
Data points do not need to be on different lines, nor do the x and y
coordinates of a data point need to be on the same line.  However,
there should be no blank lines in the input if it is to be viewed as
forming a single dataset.  Also, the x coordinates should be
monotonically increasing: the dataset must have an interpretation as a
function.

   You would construct a curve (an `interpolating spline') passing
through the points in such a dataset by doing

     spline input_file > output_file

To produce a Postscript plot of the spline with the `graph' utility,
you would do

     spline input_file | graph-ps > output.ps

To display a spline on an X Window System display, you could do

     echo 0 0 1 1 2 0 | spline | graph-X

Notice that the last example avoids the use of the input file
altogether.  `spline' will read from standard input if no files are
specified on the command line.

   What exactly does `spline' do?  First, it fits a curve through the
points in the dataset.  Then it splits the input abscissa interval
(i.e., the range of x values) into 100 sub-intervals, and computes the
y values at each of the 101 subdivision points.  It then outputs each
of the pairs (x,y).  These are the coordinates of 101 points that lie
along a curve that interpolates between the points in the dataset.  If
there is more than one dataset in the input (separated by blank lines),
each dataset is interpolated separately.

   You may use the `-n' option to replace `100' by any other integer.
You may also use the `-x' option to specify an interpolation interval
that differs from the default (the dataset abscissa range).  For
example, the command

     echo 0 0 1 0 2 0 | spline -n 20 -x 1.0 1.5 > output_file

will produce a dataset consisting of 21 (rather than 101) data points,
with x values spaced regularly between 1.0 and 1.5 (rather than between
0.0 and 2.0).  The data points will lie along a curve passing through
(0,0), (1,0), and (2.0).  This curve will be a parabola.

   In general, the interpolating curve will be a piecewise cubic spline.
That is, between each pair of adjacent `nodes' (points in the input
dataset), y will be a cubic function of x.  This function will differ,
depending on which pair of nodes x lies between.  At each node, both
the slope and curvature of the cubic pieces to either side will match.
In mathematical terms, the interpolating curve will be twice
continuously differentiable.

   `spline' supports `adding tension' to the interpolating curve.
A nonzero value for the tension may be specified with the `-t' option.
For example, a spline under considerable tension may be computed and
displayed by doing

     echo 0 0 1 0 2 0 | spline -t 10 | graph-X

As the tension parameter is increased to positive infinity, the spline
will converge to a polygonal line.  You are supposed to think of the
spline as being drawn taut.  Actually, tension may be negative as well
as positive.  A spline with negative tension will tend to bow outward,
in fact to oscillate sinusoidally.  But as the tension decreases to
negative infinity, the spline, though oscillatory, will again converge
to a polygonal line.

   If the tension is positive, its reciprocal will be the maximum
abscissa range over which the spline will `like to curve'.  Increasing
the tension far above zero will accordingly force the spline to consist
of short curved sections, centered on the data points, and sections that
are almost straight.  It follows that tension is a `dimensionful'
quantity.  If the tension is nonzero, then when the abscissa values are
multiplied by some common positive factor, the tension should be divided
by the same factor to obtain a scaled version of the original spline.
If the tension is zero (the default, or cubic spline case), then the
computation of the spline will be unaffected by linear scaling of the
data.

   In mathematical terms, a spline under tension will satisfy the
differential equation y""=sgn(tension)*(tension^2)y" between each
successive pair of nodes.  If the tension equals zero, which is the
default, the fourth derivative of y with respect to x will equal zero
at every point.  In this case, y as a function of x will reduce to a
cubic polynomial between each successive pair of nodes.  But if the
tension is nonzero, y will not be a polynomial function of x.  It may
be expressed in terms of exponential functions, however.

   Irrespective of whether or not the spline is under tension, you may
specify the `-p' option if you wish the spline to be a periodic
function of X.  This will only work if the Y values for the first and
last points in the dataset are equal.  Otherwise, it would make no
sense to compute a periodic interpolation.

   It is sometimes useful to interpolate between data points at the same
time as they are generated by an auxiliary program.  That is, it is
useful for `spline' to function as a real-time filter.  `spline' does
not normally act as a filter, since computing an interpolating curve
that is as smooth as possible is a global task.  But if the `-f' option
is specified, `spline' will indeed function as a filter.  A different
interpolation algorithm (cubic Bessel interpolation, which is local
rather than global) will be used.  If `-f' is specified, `-p' may not
be specified.  Also, if `-f' is specified then an interpolation
interval must be requested explicitly with the `-x' option.

   Cubic Bessel interpolation is inherently less smooth than the
construction of a global cubic spline.  If the `-f' option is
specified, the slope of the spline at each node will be chosen by
fitting a parabola through that node, and the two adjacent nodes.  The
slopes of the two interpolating segments to either side of each interior
node will match at that node, but typically their curvatures will not.
In mathematical terms, the interpolating curve will be continuously
differentiable, but in general not twice continuously differentiable.
This loss of differentiability is the price that is paid for functioning
as a real-time filter.

   The algorithms used by `spline' are similar to those discussed in
D. Kincaid and W. Cheney, `Numerical Analysis' (2nd ed., Brooks/Cole,
1996), section 6.4, and C. de Boor, `A Practical Guide to Splines'
(Springer-Verlag, 1978), Chapter 4.


File: plotutils.info,  Node: spline Invocation,  Next: ode,  Prev: spline Examples,  Up: Top

`spline' command-line options
=============================

   The options to `spline' are listed below.  There are three sorts of
option:

  1. Options specifying the type of interpolation to be performed.

  2. Options specifying the input or output format.

  3. Options requesting information (e.g., `--help').

Options that take an argument are followed, in parentheses, by the type
and default value of the argument.

   Besides options, the command line may include the names of one or
more input files. If no files are listed, the standard input is read.
Unless the `-a' option is used (see below), the input is expected to be
a sequence of data points, given as alternating x and y coordinates.
There may be more than one dataset per input file.  If the files are in
ASCII format (the default), datasets are separated by blank lines.

   The following options specify the type of interpolation to be
performed on each dataset.

`-f'
`--filter'
     Use a local interpolation algorithm (the cubic Bessel algorithm),
     so that `spline' may be used as a real-time filter.  The slope of
     the interpolating curve at each point in a dataset will be chosen
     by fitting a parabola through that point and the two adjacent
     points in the dataset.  If `-f' is specified then the `-x' option,
     otherwise optional, must be used as well.  Also, if `-f' is
     specified then the `-k', `-p', and `-t' options may not be used.
     If `-f' is *not* specified, then a different (global)
     interpolation algorithm will be used.

`-k K'
`--boundary-condition K'
     (Float, default 1.0.) Set the boundary condition parameter for each
     constructed spline to be K.  The spline will satisfy the two
     boundary conditions y"[0]=ky"[1] and y"[n]=ky"[n-1].  Here y[0]
     and y[1] signify the ordinate values at the first two points of a
     dataset, and y[n-1] and y[n] the ordinate values at the last two
     points.  Setting K to zero will yield a `natural' spline, i.e.,
     one that has zero curvature at the two ends of the dataset.  The
     `-k' option may not be used if `-f' or `-p' is specified.

`-n N'
`--number-of-intervals N'
     (Integer, default 100.)  Subdivide the abscissa range over which
     interpolation occurs into N subintervals.  The number of data
     points computed, and written to the output, will be n+1.

`-p'
`--periodic'
     Construct a periodic spline.  If this option is specified, the y
     values for the first and last points in each dataset must be
     equal.  The `-f' and `-k' options may not be used if `-p' is
     specified.

`-t TENSION'
`--tension TENSION'
     (Float, default 0.0.) Set the tension in each interpolating spline
     to be TENSION.  Between each pair of successive points in a
     dataset, the constructed spline will satisfy the differential
     equation y""=sgn(tension)*(tension^2)y".  If TENSION equals zero,
     the spline will be piecewise cubic.  As TENSION increases to
     positive infinity, the spline will converge to a polygonal line.
     The `-t' option may not be used if `-f' is specified.

`-x XMIN XMAX [XSPACING]'
`--x-limits XMIN XMAX [XSPACING]'
     For each dataset, set the abscissa interval over which
     interpolation occurs to be the interval between XMIN and XMAX.  If
     XSPACING is not specified, the interval will be divided into the
     number of subintervals specified by the `-n' option.  If the `-x'
     option is not used, the abscissa interval over which interpolation
     occurs will be the entire range of the dataset.  Note that the
     `-x' option may not be used if the `-f' option is used to request
     filter-like behavior (see above).

The following options specify the format of the input file(s) and the
output file.

`-a [STEP_SIZE [LOWER_LIMIT]]'
`--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]'
     (Floats, defaults 1.0 and 0.0.) Automatically generate abscissa
     values when reading the input file(s).  Irrespective of data
     format, this option indicates that the abscissa (x) values are
     missing: the dataset(s) to be read contain only ordinate (y)
     values.  The difference between successive x values will be
     STEP_SIZE, and the first x value will be LOWER_LIMIT.

`-I DATA-FORMAT'
`--input-format DATA-FORMAT'
     (Character, default `a'.)  Set the data format for the input
     file(s) to be DATA-FORMAT.  The possible data formats are as
     follows.

    `a'
          ASCII format.  Each file consists of pairs of floating point
          numbers, interpreted as the x and y coordinates of the points
          in a dataset.  The x and y coordinates of a point need not
          appear on the same line, and points need not appear on
          different lines.  But if a blank line occurs (i.e., two
          newlines in succession are seen), it is interpreted as the
          end of a dataset, and the beginning of the next.

    `d'
          Double precision binary format.  Each file is a sequence of
          double precision floating point numbers, interpreted as
          forming pairs (x,y).  If there is more than one dataset in a
          file, successive datasets are separated by a single
          occurrence of the quantity `MAXDOUBLE', which is the largest
          possible double precision floating point number.  On most
          machines this is approximately 1.8x10^308.

`-O DATA-FORMAT'
`--output-format DATA-FORMAT'
     (Character, default `a'.)  Set the data format for the output file
     to be DATA-FORMAT.  The interpretation of the DATA-FORMAT argument
     is the same as for the `-I' option.

`-P SIGNIFICANT-DIGITS'
`--precision SIGNIFICANT-DIGITS'
     (Integer, default 6.)  Set the numerical precision for the x and y
     coordinates in the output file to be SIGNIFICANT-DIGITS.  This
     takes effect only if the output file is written in `a' format,
     i.e., in ASCII.

The following options request information.
`--help'
     Print a list of command-line options, and then exit.

`--version'
     Print the version of `spline' and the plotting utilities package,
     and exit.


File: plotutils.info,  Node: ode,  Next: Appendices,  Prev: spline Invocation,  Up: Top

The `ode' Utility
*****************

   The GNU `ode' utility can produce a numerical solution to the
initial value problem for many systems of first-order ordinary
differential equations (ODE's).  `ode' may also be used to solve
systems of higher-order ODE's, since a simple procedure converts an
n'th-order equation into n first-order equations.  The output of `ode'
may easily be piped to any of the versions of `graph', so that one or
more solution curves may be plotted as they are generated.

   Three distinct schemes for numerical solution are implemented:
Runge-Kutta-Fehlberg (the default), Adams-Moulton, and Euler.  The
Runge-Kutta-Fehlberg and Adams-Moulton schemes are available with
adaptive stepsize.

* Menu:

* Basic Math::			Ordinary differential equations
* Simple ode Examples::		Simple examples using ode
* Additional ode Examples::	Additional examples using ode
* ode Invocation::		ode command-line options
* Diagnostics::			Diagnostic messages
* Numerical Error::		Numerical error and how to avoid it
* Running Time::		Time spent running ode
* Input Language::		The ode input language formally specified
* ODE Bibliography::		Bibliography on ode and ODE's


File: plotutils.info,  Node: Basic Math,  Next: Simple ode Examples,  Prev: ode,  Up: ode

Mathematical basics
===================

   We begin with some standard definitions.  A *differential equation*
is an equation involving an unknown function and its derivatives.
A differential equation is *ordinary* if the unknown function depends
on only one independent variable, often denoted t.  The *order* of the
differential equation is the order of the highest-order derivative in
the equation.  One speaks of a family, or *system* of equations when
more than one equation is involved.  If the equations are dependent on
one another, they are said to be *coupled*.  A *solution* is any
function satisfying the equations.  An *initial value problem* is
present when there exist subsidiary conditions on the unknown function
and its derivatives, all of which are given at the same value of the
independent variable.  In principle, such an `initial condition'
specifies a unique solution.  Questions about the existence and
uniqueness of a solution, along with further terminology, are discussed
in any introductory text.  (See Chapter 1 of Birkhoff and Rota's
`Ordinary Differential Equations'.  For this and other references
relevant to `ode', see *Note ODE Bibliography::.)

   In practical problems, the solution of a differential equation is
usually not expressible in terms of elementary functions.  Hence the
need for a numerical solution.

   A numerical scheme for solving an initial value problem produces an
approximate solution, using only functional evaluations and the
operations of arithmetic.  `ode' solves first-order initial value
problems of the form:

     x' = f(t,x,y,...,z)
     y' = g(t,x,y,...,z)
        .
        .
        .
     z' = h(t,x,y,...,z)

given the initial values for each dependent variable at the initial
value of the independent variable t, i.e.,

     x(a) = b
     y(a) = c
          .
          .
          .
     z(a) = d
     t = a

where a,b,c,...,d are constants.

   For `ode' to be able to solve such a problem numerically, the
functions f,g,...,g must be expressed, using the usual operators
(+,-,*,/,^), in terms of certain basic functions that `ode' recognizes.
These are the same functions that the plotting program `gnuplot'
recognizes.  Moreover, each of f,g,...,g must be given explicitly.
`ode' cannot deal with a system in which one or more of the first
derivatives is defined implicitly rather than explicitly.

   All schemes for numerical solution involve the calculation of an
approximate solution at discrete values of the independent variable t,
where the `stepsize' (the difference between any two successive values
of t, usually denoted h) may be constant or chosen adaptively.
In general, as the stepsize decreases the solution becomes more
accurate.  In `ode', the stepsize may be adjusted by the user.


File: plotutils.info,  Node: Simple ode Examples,  Next: Additional ode Examples,  Prev: Basic Math,  Up: ode

Simple examples using `ode'
===========================

   The following examples should illustrate the procedure of stating an
initial value problem and solving it with `ode'.  If these examples are
too elementary, see *Note Input Language::, for a formal specification
of the `ode' input language.  There is also a directory containing
examples of `ode' input, called `ode-examples', which is distributed
along with the GNU plotting utilities.

   Our first example is a simple one, namely

     y'(t) = y(t)

with the initial condition

     y(0) = 1

The solution to this differential equation is

     y(t) = e^t.

In particular

     y(1) = e^1 = 2.718282

to seven digits of accuracy.

   You may obtain this result with the aid of `ode' by typing on the
command line the sequence of commands

     ode
     y' = y
     y = 1
     print t, y
     step 0, 1

Two columns of numbers will appear.  Each line will show the value of
the independent variable t, and the value of the variable y, as t is
`stepped' from 0 to 1.  The last line will be

     1 2.718282

as expected.  You may use the `-p' option to change the precision.  If,
for example, you type `ode -p 10' rather than `ode', you will get ten
digits of accuracy in the output, rather than seven (the default).

   After the above output, `ode' will wait for further instructions.
Entering for example the line

     step 1, 0

should yield two more columns of numbers, containing the values of t
and y that are computed when t is stepped back from 1 to 0.  You could
type instead

     step 1, 2

to increase rather than decrease t.  To exit `ode', you would type a
line containing only `.', i.e. a single period, and tap `return'.
`ode' will also exit if it sees an end-of-file indicator in its input
stream, which you can send from your terminal by typing control-D.

   Each line of the preceding example should be self-explanatory.
A `step' statement sets the beginning and the end of an interval over
which the independent variable (here, t) will range, and causes `ode'
to set the numerical scheme in motion.  The initial value appearing in
the first `step' statement (i.e., 0) and the assignment statement

     y = 1

are equivalent to the initial condition y(0) = 1.  The statements
`y' = y' and `y = 1' are very different: `y' = y' defines a way of
computing the derivative of y, while `y = 1' sets the initial value
of y.  Whenever a `step' statement is encountered, `ode' tries to step
the independent variable through the interval it specifies.  Which
values are to be printed at each step is specified by the most recent
`print' statement.  For example,

     print t, y, y'

would cause the current value of the independent variable t, the
variable y, and its derivative to be printed at each step.

   To illustrate `ode''s ability to take its input or the initial part
of its input from a file, you could prepare a file containing the
following lines:

     # an ode to Euler
     y  = 1
     y' = y
     print t, y, y'

Call this file `euler'.  (The `#' line is a comment line, which may
appear at any point.  Everything from the `#' to the end of the line on
which it appears will be ignored.)  To process this file with `ode',
you could type on your terminal

     ode -f euler
     step 0, 1

These two lines cause `ode' to read the file `euler', and the stepping
to take place.  You will now get three quantities (t, y, and y')
printed at each of the values of t between 0 and 1.  At the conclusion
of the stepping, `ode' will wait for any further commands to be input
from the terminal.  This example illustrates that

     ode -f euler

is not equivalent to

     ode < euler

The latter would cause `ode' to take all its input from the file
`euler', while the former allows subsequent input from the terminal.
For the latter to produce output, you would need to include a `step'
line at the end of the file.  You would not need to include a `.' line,
however.  `.' is used to terminate input only when input is being read
from a terminal.

   A second simple example involves the numerical solution of a
second-order differential equation.  Consider the initial value problem

     y''(t) = -y(t)
     y(0) = 0
     y'(0) = 1

Its solution would be

     y(t) = sin(t)

To solve this problem using `ode', you must express this second-order
equation as two first-order equations.  Toward this end you would
introduce a new function, called yp say, of the independent variable t.
The pair of equations

     y' = yp
     yp' = -y

would be equivalent to the single equation above.  This sort of
reduction of an n'th order problem to n first order problems is a
standard technique.

   To plot the variable y as a function of the variable t, you could
create a file containing the lines

     # sine : y''(t) = -y(t), y(0) = 0, y'(0) = 1
     sine' = cosine
     cosine' = -sine
     sine = 0
     cosine = 1
     print t, sine

(y and yp have been renamed sine and cosine, since that is what they
will be.)  Call this file `sine'.  To display the generated data points
on an X Window System display as they are generated, you would type

     ode -f sine | graph-X -x 0 10 -y -1 1
     step 0, 2*PI
     .

After you type the `ode' line, `graph-X' will pop up a window, and
after you type the `step' line, the generated dataset will be drawn
in it.  The `-x 0 10' and `-y -1 1' options, which set the bounds for
the two axes, are necessary if you wish to display points in real time:
as they are generated.  If the axis bounds were not specified on the
command line, `graph-X' would wait until all points are read from the
input before determining the bounds, and drawing the plot.

   A slight modification of this example, showing how `ode' can
generate several datasets in succession and plot them on the same graph,
would be the following.  Suppose that you type on your terminal the
following lines.

     ode -f sine | graph-X -C -x 0 10 -y -1 1
     step 0, PI
     step PI, 2*PI
     step 2*PI, 3*PI
     .

Then the sine curve will be traced out in three stages.  Since the
output from each `step' statement ends with a blank line, `graph-X'
will treat each section of the sine curve as a different dataset.  If
you are using a color display, each of the three sections will be
plotted in a different color.  This is a feature provided by `graph-X',
which normally changes its linemode after each dataset it reads.  If
you do not like this feature, you may turn it off by using `graph-X -B'
instead of `graph-X'.

   In the above examples, you could use any of the other versions of
`graph' instead of `graph-X'.  For example, you could use `graph-ps' to
obtain a plot in encapsulated Postscript format, by typing

     ode -f sine | graph-ps > plot.ps
     step 0, 2*PI
     .

You should note that of the versions of `graph', `graph-ps' and
`graph-fig' do not produce output in real time, even when the axis
bounds are specified with the `-x' and `-y' options.  So if `graph-ps'
or `graph-fig' is used, the plot will be produced only when input from
`ode' is terminated, which will occur when you type `.'.

   In the preceding examples, the derivatives of the dependent variables
were specified by comparatively simple expressions.  They are allowed to
be arbitrarily complicated functions of the dependent variables and the
independent variable.  They also may involve any of the functions that
are built into `ode'.  `ode' has a fair number of functions built in,
including abs, sqrt, exp, log, log10, sin, cos, tan, asin, acos, atan,
sinh, cosh, tanh, asinh, acosh, and atanh.  Less familiar functions
which are built into it are besj0, besj1, besy0, besy1, erf, erfc,
inverf, lgamma, gamma, norm, invnorm, ibeta, and igamma.  These have
the same definitions as in the plotting program `gnuplot'.  (All
functions take a single argument, except for ibeta, which takes three,
and igamma, which takes two).  `ode' also knows the meaning of the
constant `PI', as the above examples show.  The names of the preceding
functions are reserved, so, for example, `cos' and `sin' may not be
used as names for variables.

   Other than the restriction of avoiding reserved names and keywords,
the names of variables may be chosen arbitrarily.  Any sequence of
alphanumeric characters starting with an alphabetic character may be
used; the first 32 characters are significant.  It is worth noting that
`ode' identifies the independent variable by the fact that it is (or
should be) the only variable that has not appeared on the left side of
a differential equation or an initial value assignment.  If there is
more than than one such variable then no stepping takes place; instead,
an error message is printed.  If there is no such variable, a dummy
independent variable is invented and given the name `(indep)',
internally.


File: plotutils.info,  Node: Additional ode Examples,  Next: ode Invocation,  Prev: Simple ode Examples,  Up: ode

Additional examples using `ode'
===============================

   We explain here how to use some additional features of `ode'.
However, the discussion below does not cover all of its capabilities.
For a complete list of command-line options, see *Note ode Invocation::.

   It is easy to use `ode' to create plots of great beauty.  An example
would be a plot of a *strange attractor*, namely the Lorenz attractor.
Suppose that a file named `lorenz' contains the following lines.

     # The Lorenz model, a system of three coupled ODE's with parameter r.
     x' = -3*(x-y)
     y' = -x*z+r*x-y
     z' = x*y-z
     
     r = 26
     x = 0; y = 1; z = 0
     
     print x, y
     step 0, 200

Then executing the command

     <lorenz ode | graph-X -C -x -10 10 -y -10 10

would produce a plot of the Lorenz attractor (strictly speaking, a plot
of one of its two-dimensional projections).  You may produce a
Postscript plot of the Lorenz attractor, and print it, by doing
something like

     <lorenz ode | graph-ps -x -10 10 -y -10 10 -W 0 | lpr

The `-W 0' ("zero width") option requests that `graph-ps' use the
thinnest line possible, to improve the visual appearance of the plot on
a printer or other Postscript device.

   Besides plotting a visually striking object in real time, the Lorenz
attractor example shows how statements may be separated by semicolons,
rather than appearing on different lines.  It also shows how to use
symbolic constants.  In the description read by `ode' the parameter r
is a variable like x, y, and z.  But unlike them it is not updated
during stepping, since no formula for its derivative r' is given.

   Our second example deals with the interactive construction of a
`phase portrait': a set of solution curves with different initial
conditions.  Phase portraits are of paramount interest in the
qualitative theory of differential equations, and also possess aesthetic
appeal.

   Since a description read by `ode' may contain any number of `step'
statements, multiple solution curves may be plotted in a single run.
The most recent `print' statement will be used with each `step'
statement.  In practice, a phase portrait would be drawn from a few
well-chosen solution curves.  Choosing a good set of solution curves
may require experimentation, which makes interactivity and real-time
plotting all-important.

   As an example, consider a so-called Lotka-Volterra predator-prey
model.  Suppose that in a lake there are two species of fish:
A (the prey) who live by eating a plentiful supply of plants, and B (the
predator) who eat A.  Let x(t) be the population of A and y(t) the
population of B at time t.  A crude model for the interaction of A
and B is given by the equations

     x' = x(a-by)
     y' = y(cx-d)

where a, b, c, d are positive constants.  To draw a phase portrait for
this system interactively, you could type

     ode | graph-X -C -x 0 5 -y 0 5
     x' = (a - b*y) * x
     y' = (c*x - d) * y
     a = 1; b = 1; c = 1; d = 1;
     print x, y
     x = 1; y = 2
     step 0, 10
     x = 1; y = 3
     step 0, 10
     x = 1; y = 4
     step 0, 10
     x = 1; y = 5
     step 0, 10
     .

Four curves will be drawn in succession, one per `step' line.  They
will be periodic; this periodicity is similar to the fluctuations
between predator and prey populations that occur in real-world
ecosystems.  On a color display the curves will appear in different
colors, since by default, `graph-X' changes the line mode between
datasets.  That feature may be turned off by using `graph-X -B' rather
than `graph-X'.

   It is sometimes useful to use `ode' and `graph' to plot discrete
points, which are not joined by line segments to form a curve.  Our
third example illustrates this.  Suppose the file `atwoods' contains
the lines

     m = 1
     M = 1.0625
     a = 0.5; adot = 0
     l = 10; ldot = 0
     
     ldot' = ( m * l * adot * adot - M * 9.8 + m * 9.8 * cos(a) ) / (m + M)
     l'    = ldot
     adot' = (-1/l) * (9.8 * sin(a) +  2 * adot * ldot)
     a'    = adot
     
     print l, ldot
     step 0, 400

The first few lines describe the functioning of a so-called swinging
Atwood's machine.  An ordinary Atwood's machine consists of a taut cord
draped over a pulley, with a mass attached to the cord at each end.
Normally, the heavier mass (M) would win against the lighter mass (m),
and draw it upward.  A swinging Atwood's machine allows the lighter
mass to swing back and forth as well as move vertically.

   The `print l, ldot' statement requests that the vertical position
and vertical velocity of the lighter mass be printed out at each step.
If you run the command

     <atwoods ode | graph-X -x 9 11 -y -1 1 -m 0 -S 1 -X l -Y ldot

you will obtain a real-time plot.  The `-m 0' option requests that
successive data points not be joined by line segments, and the `-S 1'
option requests that plotting symbol #1 (a dot) be plotted at the
location of each point.  As you will see if you run this command, the
heavy mass does not win against the lighter mass.  Instead the machine
oscillates non-periodically.  Since the motion is non-periodic, the
plot benefits from being drawn as a sequence of unconnected points.

   We conclude by mentioning a few features of `ode' that may be useful
when things are not going quite right.  One of them is the `examine'
statement.  It may be used to discover pertinent information about any
variable in a system.  For details, see *Note Input Language::.

   Another useful feature is that the `print' statement may be used to
print out more than just the value of a variable.  As we have seen, if
the name of the variable is followed by `'', the derivative of the
variable will be printed instead.  In a similar way, following the
variable name with `?', `!', or `~' prints respectively the relative
single-step error, the absolute single-step error, or the accumulated
error (not currently implemented).  These quantities are discussed in
*Note Numerical Error::.

   The `print' statement may be more complicated than was shown in the
preceding examples.  Its general structure is

     print <pr-list> [every <const>] [from <const>]

The bracket notation `[...]' means that the enclosed statements are
optional.  Until now we have not mentioned the `every' clause or the
`from' clause.  The <pr-list> is familiar, however; it is simply a
comma-separated list of variables.  For example, in the statement

     print t, y, y' every 5 from 1

the <pr-list> is <t, y, y'>.  The clauses `every 5' and `from 1'
specify that printing should take place after every fifth step, and
that the printing should begin when the independent variable t
reaches 1.  An `every' clause is useful if you wish to `thin out' the
output generated by a `step' statement, and a `from' clause is useful
if you wish to view only the final portion of a solution curve.


File: plotutils.info,  Node: ode Invocation,  Next: Diagnostics,  Prev: Additional ode Examples,  Up: ode

`ode' command-line options
==========================

The command-line options to `ode' are listed below.  There are several
sorts of option:

  1. Options affecting the way in which input is read.

  2. Options affecting the format of the output.

  3. Options affecting the choice of numerical solution scheme, and the
     error bounds that will be imposed on it.

  4. Options that request information.

The following option affects the way input is read.

`-f FILENAME'
`--input-file FILENAME'
     Read input from FILENAME before reading from standard input.

The following options affect the output format.

`-p PRECISION'
`--precision PRECISION'
     When printing numerical results, use PRECISION significant
     figures.  If this option is given, all output will be in scientific
     notation.

`-t'
`--title'
     Print a title line at the head of the output, naming the columns.
     If this option is given, the default print format will be
     scientific notation.

The following options specify the numerical integration scheme.  Only
one of the three basic option `-R', `-A', and `-E' may be specified.
The default is `-R' (Runge-Kutta-Fehlberg).

`-R [STEPSIZE]'
`--runge-kutta [STEPSIZE]'
     Use a fifth-order Runge-Kutta-Fehlberg algorithm, with an adaptive
     stepsize unless a constant stepsize is specified.  When a constant
     stepsize is specified and no error analysis is requested, then a
     classical fourth-order Runge-Kutta scheme is used.

`-A [STEPSIZE]'
`--adams-moulton [STEPSIZE]'
     Use a fourth-order Adams-Moulton predictor-corrector scheme, with
     an adaptive stepsize unless a constant stepsize, STEPSIZE, is
     specified.  The Runge-Kutta-Fehlberg algorithm is used to get past
     `bad' points (if any).

`-E [STEPSIZE]'
`--euler [STEPSIZE]'
     Use a `quick and dirty' Euler scheme, with a constant stepsize.
     The default value of STEPSIZE is 0.1.  Not recommended for serious
     applications.

`-h HMIN [HMAX]'
`--step-size-bound HMIN [HMAX]'
     Use a lower bound HMIN on the stepsize.  The numerical scheme will
     not let the stepsize go below HMIN.  The default is to allow the
     stepsize to shrink to the machine limit, i.e., the minimum nonzero
     double-precision floating point number.  The optional argument
     HMAX, if included, specifies a maximum value for the stepsize.
     It is useful in preventing the numerical routine from skipping
     quickly over an interesting region.

The following options set the error bounds on the numerical solution
scheme.

`-r RMAX [RMIN]'
`--relative-error-bound RMAX [RMIN]'
`-e EMAX [EMIN]'
`--absolute-error-bound EMAX [EMIN]'
     The `-r' option sets an upper bound on the relative single-step
     error.  If the `-r' option is used, the relative single-step error
     in any dependent variable will never exceed RMAX (the default for
     which is 10^(-9)).  If this should occur, the solution will be
     abandoned and an error message will be printed.  If the stepsize
     is not constant, the stepsize will be decreased `adaptively', so
     that the upper bound on the single-step error is not violated.
     Thus, choosing a smaller upper bound on the single-step error will
     cause smaller stepsizes to be chosen.  A lower bound RMIN may
     optionally be specified, to suggest when the stepsize should be
     increased (the default for RMIN is RMAX/1000).  The `-e' option is
     similar to `-r', but bounds the absolute rather than the relative
     single-step error.

`-s'
`--suppress-error-bound'
     Suppress the ceiling on single-step error, allowing `ode' to
     continue even if this ceiling is exceeded.  This may result in
     large numerical errors.

Finally, the following options request information.

`--help'
     Print a list of command-line options, and then exit.

`--version'
     Print the version of `ode' and the plotting utilities package, and
     exit.


File: plotutils.info,  Node: Diagnostics,  Next: Numerical Error,  Prev: ode Invocation,  Up: ode

Diagnostic messages
===================

   `ode' is always in one of two states:

   * Reading input.  The input includes a specification of a system of
     ordinary differential equations, together with instructions for
     solving it numerically: a `print' line and a `step' line.

   * Numerically solving a system, and printing the resulting output.

`ode' moves from the first to the second state after it sees and
processes a `step' line.  It returns to the first state after the
generated output has been printed.  Errors may occur in either the
`reading' state or the `solving' state, and may terminate computations
or even cause `ode' to exit.  We now explain the possible sorts of
error.

   While reading input, `ode' may encounter a syntax error: an
ungrammatical line that it is unable to parse.  (For a summary of its
input grammar, see *Note Input Language::.)  If so, it emits the error
message

     ode::nnn: syntax error

where `nnn' is the number of the line containing the error.  When the
`-f filename' option is used to specify an input file, the error
message will read

     ode:filename:nnn: syntax error

for errors encountered inside the input file.  Subsequently, when `ode'
begins reading the standard input, line numbers will start over again
from 1.

   No effort is made to recover from syntax errors in the input.
However, there is a meager effort to resynchronize, so that more than
one syntax error in a file may be found at the same time.

   It is also possible that a fatal arithmetic exception (such as a
division by zero, or a floating point overflow) may occur while `ode'
is reading input.  If such an exception occurs, `ode' will print an
"Floating point exception" error message and exit.  Arithmetic
exceptions are machine-dependent.  On some machines, the line

     y = 1/0

would induce an arithmetic exception.  Also on some machines (not
necessarily the same ones), the lines

     y = 1e100
     z = y^4

would induce an arithmetic exception.  That is because on most
machines, the double precision quantities that `ode' uses internally
are limited to a maximum size of approximately 1.8x10^308.

   When `ode' is in the `solving' state, i.e., computing a numerical
solution, similar arithmetic exceptions may occur.  If so, the solution
will be interrupted and a message resembling

     ode: arithmetic exception while calculating y'

will be printed.  However, `ode' will not exit; the exception will be
`caught'.  `ode' itself recognizes the following exceptional
conditions: square root of a negative number, logarithm of a
non-positive number, and negative number raised to a non-integer power.
`ode' will catch any of these operations before it is performed, and
print an error message specifying which illegal operation it has
encountered.

     ode: square root of a negative number while calculating y'

would be a typical error message.

   If the machine on which `ode' is running supports the `matherr'
facility for reporting errors in the computation of standard
mathematical functions, it will be used.  This facility reports domain
errors and range errors (overflows, underflows, and loss of
significance) that could occur when evaluating such functions as `log',
`gamma', etc.; again, before they are performed.  If the `matherr'
facility is present, the error message will be fairly informative.  For
example, the error message

     ode: range error (overflow) in lgamma while calculating y'

could be generated if the logarithmic gamma function `lgamma' is
evaluated at a value of its argument that is too large.  The generation
of any such message, except a message warning of an underflow, will
cause the numerical solution to be interrupted.

   There is another sort of error that may occur during numerical
solution: the condition that an error ceiling, which may be set by the
user with the `-r' option or the `-e' option, is exceeded.  This too
will cause the numerical solution to be abandoned, and `ode' to switch
back to reading input.


File: plotutils.info,  Node: Numerical Error,  Next: Running Time,  Prev: Diagnostics,  Up: ode

Numerical error and how to avoid it
===================================

   This discussion is necessarily incomplete.  Entire books exist on any
subject mentioned below (for example, floating point error).  Our goals
are modest: first, to introduce the basic notions of error analysis as
they apply to `ode'; second, to steer you around the more obvious
pitfalls.  You should look through a numerical analysis text (e.g.,
Atkinson's `Introduction to Numerical Analysis') before beginning this
discussion.

   We begin with some key definitions.  The error of greatest concern is
the difference between the actual solution and the numerical
approximation to the solution; this is termed the *accumulated error*,
since the error is built up during each numerical step.  Unfortunately,
an estimate of this error is usually not available without knowledge of
the actual solution.  There are, however, several more usable notions
of error.  The *single-step error*, in particular, is the difference
between the actual solution and the numerical approximation to the
solution after any single step, assuming the value at the beginning of
the step is correct.

   The *relative single-step error* is the single-step error, divided
by the current value of the numerical approximation to the solution.
Why not divided by the current value of the solution itself?  The reason
is that the solution is not exactly known.  When free to choose a
stepsize, `ode' will do so on the basis of the relative single-step
error.  By default, it will choose the stepsize so as to maintain an
accuracy of eight significant digits in each step.  That is, it will
choose the stepsize so as not to violate an upper bound of 10^(-9) on
the relative single-step error.  This ceiling may be adjusted with the
`-r' option.

   Where does numerical error come from?  There are two sources.  The
first is the finite precision of machine computation.  All computers
work with floating point numbers, which are not real numbers, but only
an approximation to real numbers.  However, all computations performed
by `ode' are done to double precision, so floating point error tends to
be relatively small.  You may nonetheless detect the difference between
real numbers and floating point numbers by experimenting with the `-p
17' option, which will print seventeen significant digits.  On most
machines, that is the precision of a double precision floating point
number.

   The second source of numerical error is often called the
*theoretical truncation error*.  It is the difference between the
actual solution and the approximate solution due solely to the
numerical scheme.  At the root of many numerical schemes is an infinite
series; for ordinary differential equations, it is a Taylor expansion.
Since the computer cannot compute all the terms in an infinite series,
a numerical scheme necessarily uses a truncated series; hence the term.
The single-step error is the sum of the theoretical truncation error
and the floating point error, though in practice the floating point
error is seldom included.  The single-step error estimated by `ode'
consists only of the theoretical truncation error.

   We say that a numerical scheme is *stable*, when applied to a
particular initial value problem, if the error accumulated during the
solution of the problem over a fixed interval decreases as the stepsize
decreases; at least, over a wide range of step sizes.  With this
definition both the Runge-Kutta-Fehlberg (`-R') scheme and the
Adams-Moulton (`-A') scheme are stable (a statement based more on
experience than on theoretical results) for a wide class of problems.

   After these introductory remarks, we list some common sources of
accumulated error and instability in any numerical scheme.  Usually,
problems with large accumulated error and instability are due to the
single-step error in the vicinity of a `bad' point being large.

  1. Singularities

     `ode' should not be used to generate a numerical solution on any
     interval containing a singularity.  That is, `ode' should not be
     asked to step over points at which the system of differential
     equations is singular or undefined.

     You will find the definitions of singular point, regular singular
     point, and irregular singular point in any good differential
     equations text.  If you have no favorite, try Birkhoff and Rota's
     `Ordinary Differential Equations', Chapter 9.  Always locate and
     classify the singularities of a system, if any, before applying
     `ode'.

  2. Ill-posed  problems

     For `ode' to yield an accurate numerical solution on an interval,
     the true solution must be defined and well-behaved on that
     interval.  The solution must also be real.  Whenever any of these
     conditions is violated, the problem is said to be *ill-posed*.
     Ill-posedness may occur even if the system of differential
     equations is well-behaved on the interval.  Strange results, e.g.,
     the stepsize suddenly shrinking to the machine limit or the
     solution suddenly blowing up, may indicate ill-posedness.

     As an example of ill-posedness (in fact, an undefined solution)
     consider the innocent-looking problem:

          y' = y^2
          y(1) = -1

     The solution on the domain t > 0 is

          y(t) = -1/t.

     With this problem you must not compute a numerical solution on any
     interval that includes t=0.  To convince yourself of this, try to
     use the `step' statement

          step 1, -1

     on this system.  How does `ode' react?

     In general, when using a constant stepsize you should be careful
     not to `step over' bad points or bad regions.  When allowed to
     choose a stepsize adaptively, `ode' will often spot bad points,
     but not always.

  3. Critical points

     An *autonomous* system is one that does not include the independent
     variable explicitly on the right-hand side of any differential
     equation.  A *critical point* for such a system is a point at
     which all right-hand sides equal zero.  For example, the system

          y' = 2x
          x' = 2y

     has only one critical point, at (x,y) = (0,0).

     A critical point is sometimes referred to as a *stagnation point*.
     That is because a system at a critical point will remain there
     forever, though a system near a critical point may undergo more
     violent motion.  Under some circumstances, passing near a critical
     point may give rise to a large accumulated error.

     As an exercise, solve the system above using `ode', with the
     initial condition x(0) = y(0) = 0.  The solution should be
     constant in time.  Now do the same with points near the critical
     point.  What happens?

     You should always locate the critical points of a system before
     attempting a solution with `ode'.  Critical points may be
     classified (as equilibrium, vortex, unstable, stable, etc.) and
     this classification may be of use.  To find out more about this,
     consult any book dealing with the qualitative theory of
     differential equations (e.g., Birkhoff and Rota's `Ordinary
     Differential Equations', Chapter 6).

  4. Unsuitable numerical schemes

     If the results produced by `ode' are bad in the sense that
     instability appears to be present, or an unusually small stepsize
     needs to be chosen needed in order to reduce the single-step error
     to manageable levels, it may simply be that the numerical scheme
     being used is not suited to the problem.  For example, `ode'
     currently has no numerical scheme which handles so-called `stiff'
     problems very well.

     As an example, you may wish to examine the stiff problem:

     XXX

     for 0 < t < 10.  The exact solution is

     XXX

     It is a useful exercise to solve this problem with `ode' using
     various numerical schemes, stepsizes, and relative single-step
     error bounds, and compare the generated solution curves with the
     actual solution.


   There are several rough and ready heuristic checks you can perform on
the accuracy of any numerical solution produced by `ode'.  We discuss
them in turn.

  1. Examine the stability of  solution curves: do they converge?

     That is, check how changing the stepsize affects a solution curve.
     As the stepsize decreases, the curve should converge.  If it does
     not, then either the stepsize is not small enough or the numerical
     scheme is not suited to the problem.  In practice, you would
     proceed as follows.

        * If using an adaptive stepsize, superimpose the solution
          curves for successively smaller bounds on the relative
          single-step error (obtained with, e.g., `-r 1e-9', `-r
          1e-11', `-r 1e-13', ...).  If the curves converge then the
          solution is to all appearances stable, and your accuracy is
          sufficient.

        * If employing a constant stepsize, perform a similar analysis
          by successively halving the stepsize.

     The following example is one that you may wish to experiment with.
     Make a file named `qcd' containing:

          # an equation arising in QCD (quantum chromodynamics)
          f'   = fp
          fp'  = -f*g^2
          g'   = gp
          gp'  = g*f^2
          f = 0; fp = -1; g = 1; gp = -1
          
          print t, f
          step 0, 5

     Next make a file named `stability', containing the lines:

          : sserr is the bound on the relative single-step error
          for sserr
          do
          ode -r $sserr < qcd
          done | spline -n 500 | graph-X -C

     This is a `shell script', which when run will superimpose numerical
     solutions with specified bounds on the relative single-step error.
     To run it, type:

          sh stability 1 .1 .01 .001

     and a plot of the solutions with the specified error bounds will be
     drawn.  The convergence, showing stability, should be quite
     illuminating.

  2. Check invariants of the system: are they constant?

     Many systems have invariant quantities.  For example, if the
     system is a mathematical model of a `conservative' physical system
     then the `energy' (a particular function of the dependent
     variables of the system) should be constant in time.  In general,
     knowledge about the qualitative behavior of any dependent variable
     may be used to check the quality of the solution.

  3. Check a family of solution curves: do they diverge?

     A rough idea of how error is propagated is obtained by viewing a
     family of solution curves about the numerical solution in
     question, obtained by varying the initial conditions.  If they
     diverge sharply--that is, if two solutions which start out very
     close nonetheless end up far apart--then the quality of the
     numerical solution is dubious.  On the other hand, if the curves
     do not diverge sharply then any error that is present will in all
     likelihood not increase by more than an order of magnitude or so
     over the interval.  Problems exhibiting no sharp divergence of
     neighboring solution curves are sometimes called
     *well-conditioned*.


File: plotutils.info,  Node: Running Time,  Next: Input Language,  Prev: Numerical Error,  Up: ode

Running time
============

   The time required for `ode' to solve numerically a system of
ordinary differential equations depends on a great many factors.  A few
of them are: number of equations, complexity of equations (number of
operators and nature of the operators), and number of steps taken
(a very complicated function of the difficulty of solution, unless
constant stepsizes are used).  The most effective way to gauge the time
required for solution of a system is to clock a short or imprecise run
of the problem, and reason as follows: the time required to take two
steps is roughly twice that required for one; and there is a
relationship between the number of steps required and the relative error
ceiling chosen.  That relationship depends on the numerical scheme being
used, the difficulty of solution, and perhaps on the magnitude of the
error ceiling itself.  A few carefully planned short runs may be used
to determine this relationship, enabling a long but imprecise run to be
used as an aid in projecting the cost of a more precise run over the
same region.  Lastly, if a great deal of data is printed, it is likely
that more time is spent in printing the results than in computing the
numerical solution.


File: plotutils.info,  Node: Input Language,  Next: ODE Bibliography,  Prev: Running Time,  Up: ode

The `ode' input language formally specified
===========================================

   The following is a formal description of the grammar for `ode''s
input language.  The notation is BNF, which stands for `Backus-Naur
form' (see Wirth).  Nonterminal symbols in the grammar are enclosed in
angle brackets.  Terminal tokens are in all capitals.  Bare words and
symbols stand for themselves.

     <program>    ::=        ... empty ...
                    |  <program> <statement>
     
     
     <statement>  ::=  SEP
                    |  IDENTIFIER = <const> SEP
                    |  IDENTIFIER ' = <expression> SEP
                    |  print <printlist> <optevery> <optfrom> SEP
                    |  step <const> , <const> , <const> SEP
                    |  step <const> , <const> SEP
                    |  examine IDENTIFIER SEP
     
     
     <printlist>  ::=  <printitem>
                    |  <printlist> , <printitem>
     
     
     <printitem>  ::=  IDENTIFIER
                    |  IDENTIFIER '
                    |  IDENTIFIER ?
                    |  IDENTIFIER !
                    |  IDENTIFIER ~
     
     
     <optevery>   ::=        ... empty ...
                    |  every <const>
     
     
     <optfrom>    ::=        ... empty ...
                    |  from <const>
     
     
     <const>      ::=  <expression>
     
     
     <expression> ::=  ( <expression> )
                    |  <expression> + <expression>
                    |  <expression> - <expression>
                    |  <expression> * <expression>
                    |  <expression> / <expression>
                    |  <expression> ^ <expression>
                    |  FUNCTION ( <expression> )
                    |  - <expression>
                    |  NUMBER
                    |  IDENTIFIER

Since this grammar is ambiguous, the following table summarizes the
precedences and associativities of operators within expressions.
Precedences decrease from top to bottom.

     Class           Operators    Associativity
     
     Exponential         ^            right
     Multiplicative      * /          left
     Additive            + -          left

   As noted in the grammar, there are six types of nontrivial statement.
We now explain the effects (the `semantics') of each type, in turn.

  1. IDENTIFIER ' = <expression>

     This defines a first-order differential equation.  The derivative
     of IDENTIFIER is specified by <expression>.  If a dynamic variable
     does not appear on the left side of a statement of this form, its
     derivative is assumed to be zero.  That is, it is a symbolic
     constant.

  2. IDENTIFIER = <const>

     This sets the value of IDENTIFIER to the current value of
     <expression>.  Dynamic variables that have not been initialized in
     this way are set to zero.

  3. step <const> , <const>

  4. step <const> , <const> , <const>

     A `step' statement causes the numerical scheme to be executed.  The
     first <const> is the initial value of the independent variable.
     The second is its final value.  The third is a stepsize; if given,
     it overrides any stepsize that may be specified on the command
     line.  Usually the stepsize is not specified, and it varies
     adaptively as the computation proceeds.

  5. print <printlist> [ every <const> ] [ from <const> ]

     A `print' statement controls the content and frequency of the
     numerical output.  <printlist> is a comma-separated list of
     IDENTIFIERs, where each IDENTIFIER may be followed by `'',
     denoting the derivative, or `?', denoting the relative single-step
     error, or `!', denoting the absolute single-step error, or `~',
     denoting the accumulated error (not currently implemented).  The
     specified values are printed in the order they are found.  Both the
     `every' clause and the `from' clause are optional.  If the `every'
     clause is present, a printing occurs every <const> iterations of
     the numerical algorithm.  The default is to print on every
     iteration (i.e. `every 1').  The first and last values are always
     printed.  If the `from' clause is present, it means to begin
     printing when the independent variable reaches or exceeds <const>.
     The default is to begin printing immediately.

     If no `print' statement has been supplied, then the independent
     variable and all dependent variables which have differential
     equations associated with them are printed.  The independent
     variable is printed first; the dependent variables follow in the
     order their equations were given.

  6. examine IDENTIFIER

     An `examine' statement, when executed, causes a table of
     interesting information about the named variable to be printed on
     the standard output.  For example, if the statement `examine y'
     were encountered after execution of the `ode to Euler' example
     discussed elsewhere, the output would be:

          "y" is a dynamic variable
          value:2.718282
          prime:2.718282
          sserr:1.121662e-09
          aberr:3.245638e-09
          acerr:0
           code:	push "y"

     The phrase `dynamic variable' means that there is a differential
     equation describing the behavior of y.  The numeric fields in the
     table are:

    value
          Current value of the variable.

    prime
          Current derivative of the variable.

    sserr
          Relative single-step error for the last step taken.

    aberr
          Absolute single-step error for the last step taken.

    acerr
          Total error accumulated during the most recent `step'
          statement.  Not currently implemented.

     The `code' section of the table lists the stack operations required
     to compute the derivative of y (somewhat reminiscent of a reverse
     Polish calculator).  This information may be useful in discovering
     whether the precedences in the differential equation statement
     were interpreted correctly, or in determining the time or space
     expense of a particular calculation.  `push "y"' means to load y's
     value on the stack, which is all that is required to compute its
     derivative in this case.


   The grammar for the `ode' input language contains four types of
terminal token: FUNCTION, IDENTIFIER, NUMBER, and SEP.  They have the
following meanings.

  1. FUNCTION

     One of the words: abs, sqrt, exp, log, ln, log10, sin, cos, tan,
     asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, floor,
     ceil, besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma,
     gamma, norm, invnorm, ibeta, igamma.  These are defined to have
     the same meaning as in the plotting program `gnuplot'.  All
     functions take a single argument, except for ibeta, which takes
     three, and igamma, which takes two.  For trigonometric functions,
     all arguments are expressed in radians.  The atan function is
     defined to give a value between -PI/2 and PI/2 (inclusive).

  2. IDENTIFIER

     A sequence of alphanumeric characters starting with an alphabetic
     character.  The first 32 characters are significant.  Upper and
     lower-case letters are distinct.  In identifiers, the underscore
     character is considered alphabetic.  Function names and keywords
     may not be used as identifiers, nor may `PI'.

  3. NUMBER

     A non-empty sequence of digits possibly containing a decimal point
     and possibly followed by an exponent.  An exponent is `e' or `E',
     followed by an (optionally signed) one, two, or three-digit
     number.  All numbers and all parts of numbers are radix 10.
     A number may not contain any white space.  The special word `PI' is
     a number.

  4. SEP

     A separator: a semicolon or a (non-escaped) newline.


   In the `ode' input language, upper and lower-case letters are
distinct.  Comments begin with the character `#' and continue to the
end of the line.  Long lines may be continued onto a second line by
ending the first line with a backslash (`\').  That is because the
combination backslash-newline is equivalent to a space.

   Spaces or tabs are required in the input whenever they are needed to
separate identifiers, numbers, and keywords from one another.  Except as
separators, they are ignored.


File: plotutils.info,  Node: ODE Bibliography,  Prev: Input Language,  Up: ode

Bibliography on `ode' and solving differential equations
========================================================

     K. E. Atkinson, `An Introduction to Numerical Analysis', Wiley,
     1978.  Pages 380-384 contain a nice review of the literature on
     the numerical solution of ordinary differential equations.

     G. Birkhoff and G. Rota, `Ordinary Differential Equations', Ginn
     and Co., 1962.

     N. B. Tufillaro, T. Abbott, and J. Reilly, `An Experimental
     Approach to Nonlinear Dynamics and Chaos', Addison-Wesley, 1992.
     Appendix C discusses an earlier version of `ode'.

     N. B. Tufillaro, E. F. Redish, and J. S. Risley, "`ode':
     A numerical simulation of ordinary differential equations," pp.
     480-481 in `Proceedings of the Conference on Computers in Physics
     Instruction', Addison-Wesley, 1990.

     N. Wirth, `Algorithms + Data Structures = Programs',
     Prentice-Hall, 1976.


File: plotutils.info,  Node: Appendices,  Prev: ode,  Up: Top

   The following appendices contain miscellaneous information on the
plotting utilities.

* Menu:

* Text and Markers::	Text fonts, text strings, and marker symbols
* Color Names::		Specifying colors by name
* Metafiles::           The device-independent GNU metafile format
* Auxiliary Software::  How to obtain auxiliary software
* Acknowledgements::    The Contributors


File: plotutils.info,  Node: Text and Markers,  Next: Color Names,  Prev: Appendices,  Up: Appendices

Fonts, Strings, and Symbols
***************************

   The `libplot' function library and applications linked with it, such
as `graph', can draw text strings in a wide variety of fonts.  Text
strings may include characters from more than one font in a typeface,
and may include superscripts, subscripts, and square roots.  A wide
variety of plotting symbols can also be drawn.  The following sections
explain how to use these features.

* Menu:

* Text Fonts::		Available text fonts
* Text String Format::	Text string formatting (with escape sequences)
* Marker Symbols::	Available marker symbols


File: plotutils.info,  Node: Text Fonts,  Next: Text String Format,  Prev: Text and Markers,  Up: Text and Markers

Available text fonts
====================

   The `libplot' function library and applications linked with it, such
as `graph', can use many fonts.  These include 16 Hershey fonts and 35
Postscript fonts.  We call these 51 fonts the `built-in' fonts.  The
Hershey fonts are so-called vector fonts, constructed from stroked
characters digitized c. 1967 by Dr. Allen V. Hershey at the U.S. Naval
Surface Weapons Center in Dahlgren, VA.  The 35 Postscript fonts are
the fonts built into most modern Postscript printers.  The Hershey
fonts may be used by all versions of `libplot', and the Postscript
fonts may be used by all versions of `libplot' except `libplottek'.  So
all versions of `graph' may use the Hershey fonts, and all versions of
`graph' except `graph-tek' may use the Postscript fonts.

   For the purpose of plotting text strings (*note Text String
Format::.), the built-in fonts are divided into typefaces.  The 16
Hershey fonts are divided into typefaces as follows.

   * HersheySerif
       1. HersheySerif

       2. HersheySerif-Italic

       3. HersheySerif-Bold

       4. HersheySerif-BoldItalic

       5. HersheyCyrillic

       6. HersheyEUC

   * HersheySans
       1. HersheySans

       2. HersheySans-Oblique

       3. HersheySans-Bold

       4. HersheySans-BoldOblique

   * HersheyScript
       1. HersheyScript

       2. HersheyScript

       3. HersheyScript-Bold

       4. HersheyScript-Bold

   * HersheyGothic-English

   * HersheyGothic-German

   * HersheyGothic-Italian

   * HersheySerif-Symbol

   * HersheySans-Symbol

The three HersheyGothic fonts are singletons: each is font #1 of its own
typeface.  The two symbol fonts play a special role.  By convention,
each Hershey typeface contains a symbol font (HersheySerif-Symbol or
HersheySans-Symbol, as appropriate) as font #0.

   The 35 Postscript fonts are divided into typefaces as follows.

   * Helvetica
       1. Helvetica

       2. Helvetica-Oblique

       3. Helvetica-Bold

       4. Helvetica-BoldOblique

   * Helvetica-Narrow
       1. Helvetica-Narrow

       2. Helvetica-Narrow-Oblique

       3. Helvetica-Narrow-Bold

       4. Helvetica-Narrow-BoldOblique

   * Times
       1. Times-Roman

       2. Times-Italic

       3. Times-Bold

       4. Times-BoldItalic

   * AvantGarde
       1. AvantGarde-Book

       2. AvantGarde-BookOblique

       3. AvantGarde-Demi

       4. AvantGarde-DemiOblique

   * Bookman
       1. Bookman-Light

       2. Bookman-LightItalic

       3. Bookman-Demi

       4. Bookman-DemiItalic

   * Courier
       1. Courier

       2. Courier-Oblique

       3. Courier-Bold

       4. Courier-BoldOblique

   * NewCenturySchlbk
       1. NewCenturySchlbk-Roman

       2. NewCenturySchlbk-Italic

       3. NewCenturySchlbk-Bold

       4. NewCenturySchlbk-BoldItalic

   * Palatino
       1. Palatino-Roman

       2. Palatino-Italic

       3. Palatino-Bold

       4. Palatino-BoldItalic

   * ZapfChancery-MediumItalic

   * ZapfDingbats

   * Symbol

The two Zapf fonts are singletons: each is font #1 of its own typeface.
The Symbol font plays a special role.  By convention, each Postscript
typeface contains the Symbol font as font #0.

   As you can see from the above tables, our convention is that in any
typeface with more than a single font, font #1 is the normal font, font
#2 is italic or oblique, font #3 is bold, and font #4 is bold italic or
bold oblique.  Additional variants (if any) are numbered #5 and higher.

   Of the 51 built-in fonts, all except for the three symbol fonts,
HersheyCyrillic, HersheyEUC, and ZapfDingbats are ISO-8859-1 fonts.
This means that they use the ISO-Latin-1 encoding, which is a superset
of ASCII.  The three symbol fonts use a special encoding, since they
consist of Greek characters and mathematical symbols.  The ZapfDingbats
font, which consists largely of marker symbols, uses a special encoding
also.  These two encodings are documented in the `Postscript Language
Reference Manual'.

   The HersheyCyrillic font uses an encoding known as KOI8-R, a
superset of ASCII which has become the de facto standard for Unix and
networking applications in the former Soviet Union.  Insofar as
printable ASCII characters go, it is the same as the HersheySerif font.
But its `8-bit' characters are different.  The byte range 0xc0...0xdf
contains lower-case Cyrillic characters and the byte range 0xe0...0xff
contains upper case Cyrillic characters.  Additional Cyrillic
characters are located at 0xa3 and 0xb3.  For more on this encoding, see
`http://www.nagual.pp.ru/~ache/koi8.html' and the document known as
Internet RFC 1489.

   The HersheyEUC font is used for displaying Japanese.  EUC stands for
`extended Unix code', which is a scheme for encoding Japanese, and also
other character sets (e.g., Greek and Cyrillic) as multibyte character
strings.  The format of EUC strings is discussed in Ken Lunde's
`Understanding Japanese Information Processing' (O'Reilly, 1993), which
contains much additional information on Japanese text processing.  See
also his on-line supplement,
`http://www.ora.com/people/authors/lunde/cjk_inf.html'.

   In the HersheyEUC font, characters in the printable ASCII range,
0x20...0x7e, are similar to US ASCII (they are `JIS Roman', an ASCII
variant standardized by the Japanese Industrial Standards Committee).
Each successive pair of bytes in the `0xa1'...`0xfe' range defines a
single character in the JIS X0208 standard.  The characters in the JIS
X0208 standard include Japanese syllabic characters (Hiragana and
Katakana), ideographic characters (Kanji), Roman, Greek, and Cyrillic
alphabets, punctuation marks, and miscellaneous symbols.  For example,
the JIS X0208 standard indexes the 83 Hiragana as `0x2421'...`0x2453'.
To obtain the EUC code for any JIS X0208 character, one adds `0x80' to
each byte (i.e., `sets the high bit' on each byte).  So the first of
the 83 Hiragana (`0x2421') would be encoded as the successive pair of
bytes `0xa4' and `0xa1'.

   The implementation of the JIS X0208 standard in the HersheyEUC font
is based on Dr. Hershey's digitizations, and is complete enough to be
useful.  All Hiragana and Katakana are available, though the little-used
`half-width Katakana' are not supported.  Also, 603 frequently used
Kanji are available.  The Hiragana, the Katakana, and the available
Kanji all have the same width.  The file `kanji.doc', which is
distributed along with the GNU plotting utilities, lists the 603
available Kanji.  Each JIS X0208 character that is unavailable will be
drawn as an `undefined character' glyph (several horizontal lines).

   To what extent do the Hershey and Postscript fonts contain ligatures?
The 35 Postscript fonts, as implemented in `libplot', do not contain
ligatures.  However, four of the 16 Hershey fonts contain ligatures.
The character combinations "fi", "ff", "fl", "ffi", and "ffl" are
automatically drawn as ligatures in HersheySerif and
HersheySerif-Italic.  (Also in HersheyCyrillic and HersheyEUC, since
insofar as printable ASCII characters are concerned, they are identical
[or almost identical] to HersheySerif.)  In addition, "tz" and "ch" are
ligatures in HersheyGothic-German.  The German `eszet' double-s
character is not regarded as a ligature in any font.  To obtain it, you
must either request it with the control sequence "\ss" (*note Text
String Format::.), or, if you have an 8-bit keyboard, type it
explicitly.

   The preceding discussions dealt with the built-in fonts: the 16
Hershey and 35 Postscript fonts.  In fact `libplotX' and `graph-X'
(which is built on top of `libplotX') are not restricted to the
built-in fonts.  They can display text strings using certain X Window
System fonts as well.  Any scalable font which is available on the
current X Window System display, and which has a so-called XLFD
(X Logical Font Description) name, may be used.  For example, the font
"-monotype-gill sans-ultrabold-r-condensed-0-0-0-0-p-0-iso8859-1" is
available on some X displays.  It would be referred to by `libplotX' as
"gill sans-ultrabold-r-condensed".  The command

     echo 0 0 1 1 2 0 | graph-X -F "gill sans-ultrabold-r-condensed"

would draw a plot on an X display, in which all axis ticks are labeled
in this font.

   You may determine which fonts are available on an X display by using
the `xlsfonts' command.  Fonts whose names end in
"-0-0-0-0-p-0-iso8859-1" or "-0-0-0-0-m-0-iso8859-1" are scalable
ISO-Latin-1 fonts that may be used by `libplotX' and `graph-X'.  The
two sorts of font are variable-width and fixed-width fonts,
respectively.  Fonts whose names end in "adobe-fontspecific" may also
be used.  They are fonts that do not employ the ISO-Latin-1 encoding.

   The escape sequences which allow access to mathematical symbols and
Greek characters (*note Text String Format::.) may be employed when
using any X Window System font.  Also, the escape sequences which allow
access to the special non-ASCII characters in any of the built-in
ISO-Latin-1 fonts may be employed when using any ISO-Latin-1 X Window
System font.


File: plotutils.info,  Node: Text String Format,  Next: Marker Symbols,  Prev: Text Fonts,  Up: Text and Markers

Text string format and escape sequences
=======================================

   Text strings that are drawn by `libplot', and by such applications
as `graph' that are built on `libplot', must consist of printable
characters.  No embedded control characters, such as newlines or
carriage returns, are allowed.  Technically, a character is `printable'
if it comes from either of the two byte ranges 0x20...0x7e and
0xa0...0xff.  The former is the printable ASCII range.

   Text strings may, however, include embedded `escape sequences' that
shift the font, append subscripts or superscripts, or include special
mathematical symbols.  As a consequence, the axis labels on a plot
prepared with `graph' may include such features.

   The format of the escape sequences should look familiar to anyone
who is familiar with the TeX or `groff' document formatters.  Each
escape sequence consists of three characters: a backslash, and two
characters that specify the control code.  The most frequently used
escape sequences are as follows.

"\sp"
     start superscript mode

"\ep"
     end superscript mode

"\sb"
     start subscript mode

"\eb"
     end subscript mode

"\mk"
     mark location

"\rt"
     return to marked location

For example, the string "x\sp2\ep" would be interpreted as `x squared'.
Subscripts on subscripts, etc., are allowed.  Subscripts and
superscripts may be vertically aligned by judicious use of the "\mk" and
"\rt" escape sequences.  For example, "a\mk\sbi\eb\rt\sp2\ep" produces
"a sub i squared", with the exponent `2' placed immediately above the
subscript.

   There are also escape sequences that switch from font to font within
a typeface.  For an enumeration of the fonts within each typeface, see
*Note Text Fonts::.  Suppose for example that the current font is
`Times-Roman', which is font #1 in the `Times' typeface.  The string "A
\f2very\f1 well labeled axis" would be a string in which the word `very'
appears in Times-Italic rather than Times-Roman.  That is because
Times-Italic is the #2 font in the typeface.  Font-switching escape
sequences are of the form "\fN", where N is the number of the font to
be switched to, in the current font.  There is currently no support for
switching between fonts in different typefaces.

   There are also a few escape sequences for horizontal shifts, which
are useful for improving horizontal alignment, such as when shifting
between fonts.  "\r1", "\r2", "\r4", "\r6", "\r8" are escape sequences
that shift right by 1 em, 1/2 em, 1/4 em, 1/6 em, and 1/8 em,
respectively.  "\l1", "\l2", "\l4", "\l6", "\l8" are similar, but shift
left instead of right.  "A \f2very\r8\f1 well labeled axis" would look
better than "A \f2very\f1 well labeled axis".

   Square roots are handled with the aid of a special pair of escape
sequences, together with the "\mk" and "\rt" sequences discussed above.
A square root symbol is begun with "\sr", and continued arbitrarily far
to the right with the overbar (`run') escape sequence, "\rn".  For
example, the string "\sr\mkab\rt\rn\rn" would be plotted as `the square
root of ab'.  To adjust the length of the overbar, you may need to
experiment with the number of times "\rn" appears.

   To underline a string, you would use "\ul", the underline escape
sequence, one or more times.  The "\mk"..."\rt" trick would be employed
in the same way.  So, for example, "\mkabc\rt\ul\ul\ul" would yield an
underlined "ABC".  To adjust the length of the underline, you may need
to experiment with the number of times "\ul" appears.  You may also
need to use one or more of the abovementioned horizontal shifts.  For
example, if the "HersheySerif" font were used, "\mkabc\rt\ul\ul\l8\ul"
would yield a better underline than "\mkabc\rt\ul\ul\ul".

   Besides the preceding escape sequences, there are also escape
sequences for the printable non-ASCII characters in each of the built-in
ISO-Latin-1 fonts (which means in every built-in font, except for the
symbol fonts, HersheyCyrillic, HersheyEUC, and ZapfDingbats).  Such
`8-bit' characters, in the 0xa0...0xff byte range, may be included
directly in a text string.  But if your editor does not permit this,
you may use the escape sequences for them instead.  The useful
non-ASCII characters include accented characters, among others.

   There are escape sequences for the mathematical symbols and Greek
characters in the symbol fonts, as well.  Which font the mathematical
symbols and Greek characters are taken from depends on whether your
current font is a Hershey font or a Postscript font.  The symbols are
taken from the HersheySerif-Symbol font or the HersheySans-Symbol font
in the former case, and from the Symbol font in the latter.

   The following are the escape sequences that provide access to the
non-ASCII characters of the current font, provided that it is an
ISO-Latin-1 font.  Each escape sequence is followed by the position of
the corresponding character in the ISO-Latin-1 encoding (in decimal),
and the official Postscript name of the character.  Most names should be
self-explanatory.  For example, `eacute' is a lower-case `e', equipped
with an acute accent.

"\r!"
     [161] exclamdown

"\ct"
     [162] cent

"\Po"
     [163] sterling

"\Cs"
     [164] currency

"\Ye"
     [165] yen

"\bb"
     [166] brokenbar

"\sc"
     [167] section

"\ad"
     [168] dieresis

"\co"
     [169] copyright

"\Of"
     [170] ordfeminine

"\Fo"
     [171] guillemotleft

"\no"
     [172] logicalnot

"\hy"
     [173] hyphen

"\rg"
     [174] registered

"\a-"
     [175] macron

"\de"
     [176] degree

"\+-"
     [177] plusminus

"\S2"
     [178] twosuperior

"\S3"
     [179] threesuperior

"\aa"
     [180] acute

"\*m"
     [181] mu

"\ps"
     [182] paragraph

"\md"
     [183] periodcentered

"\ac"
     [184] cedilla

"\S1"
     [185] onesuperior

"\Om"
     [186] ordmasculine

"\Fc"
     [187] guillemotright

"\14"
     [188] onequarter

"\12"
     [189] onehalf

"\34"
     [190] threequarters

"\r?"
     [191] questiondown

"\`A"
     [192] Agrave

"\'A"
     [193] Aacute

"\^A"
     [194] Acircumflex

"\~A"
     [195] Atilde

"\:A"
     [196] Adieresis

"\oA"
     [197] Aring

"\AE"
     [198] AE

"\,C"
     [199] Ccedilla

"\`E"
     [200] Egrave

"\'E"
     [201] Eacute

"\^E"
     [202] Ecircumflex

"\:E"
     [203] Edieresis

"\`I"
     [204] Igrave

"\'I"
     [205] Iacute

"\^I"
     [206] Icircumflex

"\:I"
     [207] Idieresis

"\-D"
     [208] Eth

"\~N"
     [209] Ntilde

"\'O"
     [210] Ograve

"\'O"
     [211] Oacute

"\^O"
     [212] Ocircumflex

"\~O"
     [213] Otilde

"\:O"
     [214] Odieresis

"\mu"
     [215] multiply

"\/O"
     [216] Oslash

"\`U"
     [217] Ugrave

"\'U"
     [218] Uacute

"\^U"
     [219] Ucircumflex

"\:U"
     [220] Udieresis

"\'Y"
     [221] Yacute

"\TP"
     [222] Thorn

"\ss"
     [223] germandbls

"\`a"
     [224] agrave

"\'a"
     [225] aacute

"\^a"
     [226] acircumflex

"\~a"
     [227] atilde

"\:a"
     [228] adieresis

"\oa"
     [229] aring

"\ae"
     [230] ae

"\,c"
     [231] ccedilla

"\`e"
     [232] egrave

"\'e"
     [233] eacute

"\^e"
     [234] ecircumflex

"\:e"
     [235] edieresis

"\`i"
     [236] igrave

"\'i"
     [237] iacute

"\^i"
     [238] icircumflex

"\:i"
     [239] idieresis

"\Sd"
     [240] eth

"\~n"
     [241] ntilde

"\`o"
     [242] ograve

"\'o"
     [243] oacute

"\^o"
     [244] ocircumflex

"\~o"
     [245] otilde

"\:o"
     [246] odieresis

"\di"
     [247] divide

"\/o"
     [248] oslash

"\`u"
     [249] ugrave

"\'u"
     [250] uacute

"\^u"
     [251] ucircumflex

"\:u"
     [252] udieresis

"\'y"
     [253] yacute

"\Tp"
     [254] thorn

"\:y"
     [255] ydieresis

   The following are the escape sequences that provide access to
mathematical symbols and Greek characters in the current symbol font,
whether HersheySerif-Symbol or HersheySans-Symbol (for Hershey fonts) or
Symbol (for Postscript fonts).  Each escape sequence is followed by the
position (in octal) of the corresponding character in the symbol
encoding, and the official Postscript name of the character.  Many
escape sequences and names should be self-explanatory.  "\*a" represents
a lower-case Greek alpha, for example.  For a table displaying each of
the characters below, see the `Postscript Language Reference Manual'.

"\fa"
     [0042] universal

"\te"
     [0044] existential

"\st"
     [0047] suchthat

"\**"
     [0052] asteriskmath

"\=~"
     [0100] congruent

"\*A"
     [0101] Alpha

"\*B"
     [0102] Beta

"\*X"
     [0103] Chi

"\*D"
     [0104] Delta

"\*E"
     [0105] Epsilon

"\*F"
     [0106] Phi

"\*G"
     [0107] Gamma

"\*Y"
     [0110] Eta

"\*I"
     [0111] Iota

"\+h"
     [0112] theta1

"\*K"
     [0113] Kappa

"\*L"
     [0114] Lambda

"\*M"
     [0115] Mu

"\*N"
     [0116] Nu

"\*O"
     [0117] Omicron

"\*P"
     [0120] Pi

"\*H"
     [0121] Theta

"\*R"
     [0122] Rho

"\*S"
     [0123] Sigma

"\*T"
     [0124] Tau

"\*U"
     [0125] Upsilon

"\ts"
     [0126] sigma1

"\*W"
     [0127] Omega

"\*C"
     [0130] Xi

"\*Q"
     [0131] Psi

"\*Z"
     [0132] Zeta

"\tf"
     [0134] therefore

"\pp"
     [0136] perpendicular

"\ul"
     [0137] underline

"\rx"
     [0140] radicalex

"\*a"
     [0141] alpha

"\*b"
     [0142] beta

"\*x"
     [0143] chi

"\*d"
     [0144] delta

"\*e"
     [0145] epsilon

"\*f"
     [0146] phi

"\*g"
     [0147] gamma

"\*y"
     [0150] eta

"\*i"
     [0151] iota

"\+f"
     [0152] phi1

"\*k"
     [0153] kappa

"\*l"
     [0154] lambda

"\*m"
     [0155] mu

"\*n"
     [0156] nu

"\*o"
     [0157] omicron

"\*p"
     [0160] pi

"\*h"
     [0161] theta

"\*r"
     [0162] rho

"\*s"
     [0163] sigma

"\*t"
     [0164] tau

"\*u"
     [0165] upsilon

"\+p"
     [0166] omega1

"\*w"
     [0167] omega

"\*c"
     [0170] xi

"\*q"
     [0171] psi

"\*z"
     [0172] zeta

"\ap"
     [0176] similar

"\+U"
     [0241] Upsilon1

"\fm"
     [0242] minute

"\<="
     [0243] lessequal

"\f/"
     [0244] fraction

"\if"
     [0245] infinity

"\Fn"
     [0246] florin

"\CL"
     [0247] club

"\DI"
     [0250] diamond

"\HE"
     [0251] heart

"\SP"
     [0252] spade

"\<>"
     [0253] arrowboth

"\<-"
     [0254] arrowleft

"\ua"
     [0255] arrowup

"\->"
     [0256] arrowright

"\da"
     [0257] arrowdown

"\de"
     [0260] degree

"\+-"
     [0261] plusminus

"\sd"
     [0262] second

"\>="
     [0263] greaterequal

"\mu"
     [0264] multiply

"\pt"
     [0265] proportional

"\pd"
     [0266] partialdiff

"\bu"
     [0267] bullet

"\di"
     [0270] divide

"\!="
     [0271] notequal

"\=="
     [0272] equivalence

"\~~"
     [0273] approxequal

"\.."
     [0274] ellipsis

NONE
     [0275] arrowvertex

"\an"
     [0276] arrowhorizex

"\CR"
     [0277] carriagereturn

"\Ah"
     [0300] aleph

"\Im"
     [0301] Ifraktur

"\Re"
     [0302] Rfraktur

"\wp"
     [0303] weierstrass

"\c*"
     [0304] circlemultiply

"\c+"
     [0305] circleplus

"\es"
     [0306] emptyset

"\ca"
     [0307] cap

"\cu"
     [0310] cup

"\SS"
     [0311] superset

"\ip"
     [0312] reflexsuperset

"\n<"
     [0313] notsubset

"\SB"
     [0314] subset

"\ib"
     [0315] reflexsubset

"\mo"
     [0316] element

"\nm"
     [0317] notelement

"\/_"
     [0320] angle

"\gr"
     [0321] nabla

"\rg"
     [0322] registerserif

"\co"
     [0323] copyrightserif

"\tm"
     [0324] trademarkserif

"\PR"
     [0325] product

"\sr"
     [0326] radical

"\md"
     [0327] dotmath

"\no"
     [0330] logicalnot

"\AN"
     [0331] logicaland

"\OR"
     [0332] logicalor

"\hA"
     [0333] arrowdblboth

"\lA"
     [0334] arrowdblleft

"\uA"
     [0335] arrowdblup

"\rA"
     [0336] arrowdblright

"\dA"
     [0337] arrowdbldown

"\lz"
     [0340] lozenge

"\la"
     [0341] angleleft

"\RG"
     [0342] registersans

"\CO"
     [0343] copyrightsans

"\TM"
     [0344] trademarksans

"\SU"
     [0345] summation

NONE
     [0346] parenlefttp

NONE
     [0347] parenleftex

NONE
     [0350] parenleftbt

"\lc"
     [0351] bracketlefttp

NONE
     [0352] bracketleftex

"\lf"
     [0353] bracketleftbt

"\lt"
     [0354] bracelefttp

"\lk"
     [0355] braceleftmid

"\lb"
     [0356] braceleftbt

"\bv"
     [0357] braceex

NONE
     [0360] applelogo

"\ra"
     [0361] angleright

"\is"
     [0362] integral

NONE
     [0363] integraltp

NONE
     [0364] integralex

NONE
     [0365] integralbt

NONE
     [0366] parenrighttp

NONE
     [0367] parenrightex

NONE
     [0370] parenrightbt

"\rc"
     [0371] bracketrighttp

NONE
     [0372] bracketrightex

"\rf"
     [0373] bracketrightbt

"\RT"
     [0374] bracerighttp

"\rk"
     [0375] bracerightmid

"\rb"
     [0376] bracerightbt

   Finally, there are escape sequences that apply only if the current
font is a Hershey font.  Most of these escape sequences provide access
to special symbols that belong to no font, and are accessible by no
other means.  These symbols are of two sorts: miscellaneous and
astronomical.  The escape sequences for the miscellaneous symbols are
as follows.

"\dd"
     daggerdbl

"\dg"
     dagger

"\hb"
     hbar

"\li"
     lineintegral

"\IB"
     interbang

"\Lb"
     lambdabar

"\~-"
     modifiedcongruent

"\-+"
     minusplus

"\||"
     parallel

"\s-"
     [variant form of s]

The final escape sequence in the table above, "\s-", yields a letter
rather than a symbol.  It is provided because in some Hershey fonts, the
shape of the lower-case letter `s' differs if it is the last letter in
a word.  This is the case for HersheyGothic-German.  The German word
"besonders", for example, should be written as "besonder\s-" if it is to
be rendered correctly in this font.  The same is true for the two
Hershey symbol fonts, with their Greek alphabets (in Greek text,
lower-case final `s' is different from lower-case non-final `s').
In Hershey fonts where there is no distinction between final and
non-final `s', "s" and "\s-" are equivalent.

   The escape sequences for the astronomical symbols are listed in the
following table.  We stress that that like the preceding miscellaneous
escape sequences, they apply only if the current font is a Hershey font.

"\SO"
     sun

"\ME"
     mercury

"\VE"
     venus

"\EA"
     earth

"\MA"
     mars

"\JU"
     jupiter

"\SA"
     saturn

"\UR"
     uranus

"\NE"
     neptune

"\PL"
     pluto

"\LU"
     moon

"\CT"
     comet

"\ST"
     star

"\AS"
     ascendingnode

"\DE"
     descendingnode

   The preceding miscellaneous and astronomical symbols are not the only
special non-font symbols that may be used if the current font is a
Hershey font.  The entire library of glyphs digitized by Dr. Allen V.
Hershey is built into GNU `libplot'.  So text strings may include any
Hershey glyph.  Each of the 1641 available Hershey glyphs is identified
by a four-digit number.  Standard Hershey glyph #1 would be specified
as "\#H0001".  The standard Hershey glyphs range from "\#H0001" to
"\#H3999", with a number of gaps.  Some additional glyphs designed by
others appear in the "\#H4000"..."\#H4194" range.  Syllabic Japanese
characters (Kana) are located in the "\#H4195"..."\#H4399" range.

   You may order a table of nearly all the Hershey glyphs in the
"\#H0001"..."\#H3999" range from the U.S. National Technical
Information Service, at +1 703 487 4650.  Ask for item number PB251845;
the current price is about US$40.  By way of example, the string

     "\#H0744\#H0745\#H0001\#H0002\#H0003\#H0869\#H0907\#H2330\#H2331"

when drawn will display a shamrock, a fleur-de-lis, cartographic (small)
letters A, B, C, a bell, a large circle, a treble clef, and a bass
clef.  Again, this assumes that the current font is a Hershey font.

   You may also use Japanese syllabic characters (Hiragana and Katakana)
and ideographic characters (Kanji) when drawing strings in any Hershey
font.  In all, 603 Kanji are available; these are the same Kanji that
are available in the HersheyEUC font.  The Japanese characters are
indexed according to the JIS X0208 standard for Japanese typography,
which represents each character by a two-byte sequence.  Each JIS X0208
character would be specified by an escape sequence which expresses this
two-byte sequence as four hexadecimal digits, such as "\#J357e".  Both
bytes must be in the `0x21'...`0x7e' range in order to define a JIS
X0208 character.  Kanji are located at "\#J3021" and above.  The file
`kanji.doc', which is distributed along with the GNU plotting
utilities, lists the available Kanji.

   Characters appearing elsewhere in the JIS X0208 encoding may be
accessed similarly.  For example, Hiragana and Katakana are located in
the "\#J2421"..."\#J257e" range, and Roman characters are located in the
"\#J2300"..."\#J237e" range.  The file `kana.doc' lists the encodings
of the Hiragana and Katakana.  For more on the JIS X0208 standard, see
Ken Lunde's `Understanding Japanese Information Processing' (O'Reilly,
1993), and his on-line supplement,
`http://www.ora.com/people/authors/lunde/cjk_inf.html'.

   The Kanji numbering used in A. N. Nelson's `Modern Reader's
Japanese-English Character Dictionary', a longtime standard, is also
supported.  (This dictionary is published by C. E. Tuttle and Co., with
ISBN 0-8048-0408-7.  A revised edition [ISBN 0-8048-2036-8] is due in
1997, but uses a different numbering.)  `Nelson' escape sequences for
Kanji are similar to JIS X0208 escape sequences, but use four decimal
instead of four hexadecimal digits.  The file `kanji.doc' gives the
correspondence between the JIS numbering scheme and the Nelson
numbering scheme.  For example, "\#N0001" is equivalent to "\#J306c".
It also gives the positions of the available Kanji in the Unicode
encoding.

   All available Kanji have the same width, which is the same as that of
the syllabic Japanese characters (Hiragana and Katakana).  Each Kanji
that is not available will print as an `undefined character' glyph (a
set of horizontal lines).  The same is true for non-Kanji JIS X0208
characters which are not available.


File: plotutils.info,  Node: Marker Symbols,  Prev: Text String Format,  Up: Text and Markers

Available marker symbols
========================

   All versions of the GNU `libplot' library support the same set of
marker symbols, numbered 0 through 31.  These are the symbols that the
`graph' program will plot at each point of a dataset, if the `-S'
option is used.  The list is as follows (by convention, marker symbol
#0 means no symbol at all).

  0. no symbol at all

  1. dot

  2. plus (+)

  3. asterisk (*)

  4. circle

  5. cross

  6. square

  7. triangle

  8. diamond

  9. star

 10. inverted triangle

 11. starburst

 12. fancy plus

 13. fancy cross

 14. fancy square

 15. fancy diamond

 16. filled circle

 17. filled square

 18. filled triangle

 19. filled diamond

 20. filled inverted triangle

 21. filled fancy square

 22. filled fancy diamond

 23. half filled circle

 24. half filled square

 25. half filled triangle

 26. half filled diamond

 27. half filled inverted triangle

 28. half filled fancy square

 29. half filled fancy diamond

 30. octagon

 31. filled octagon

The interpretation of marker symbols 1 through 5 is the same as in the
GKS (Graphics Kernel System).

   Symbols 32 and up are interpreted as characters in a certain text
font.  For `libplot', it is the current font.  For `graph', it is the
font selected with the `--symbol-font-name' option.  By default, this
is the ZapfDingbats font except in `graph-tek'.  `graph-tek' currently
has no access to Postscript fonts, so it uses the `HersheySerif' font
instead.

   Many of the characters in the ZapfDingbats font are suitable for use
as marker symbols.  For example, character #74 is the Texas star.  Doing

     echo 0 0 1 2 2 1 3 2 4 0 | graph-ps -m 0 -S 74 0.1 > plot.ps

will produce a Postscript plot consisting of five data points, not
joined by line segments.  Each data point will be marked by a Texas
star, of a large font size (0.1 times the width of the plotting box).


File: plotutils.info,  Node: Color Names,  Next: Metafiles,  Prev: Text and Markers,  Up: Appendices

Specifying Colors by Name
*************************

   Many of the plotting utilities allow colors to be specified by name.
For example, `graph' supports the `--frame-color' option.  The
`libplot' function library includes the pencolorname and fillcolorname
functions.  All of these take a single string as an argument.  It is
interpreted as the name of a color.

   665 distinct color names are recognized, including obscure ones like
"dark magenta", "forest green", and "olive drab".  Color names are
case-insensitive, and spaces are ignored.  So, for example, "RosyBrown"
is equivalent to "rosy brown", and "DarkGoldenrod3" to "dark goldenrod
3".

   The file `colors.txt', which is distributed along with the GNU
plotting utilities, lists the available color names.  They are
essentially the color names recognized by recent versions of the
X Window System, which on most machines are listed in the file
`/usr/lib/X11/rgb.txt'.  However, for every color name containing the
string "gray", a version containing "grey" has been included.  For
example, both "dark slate gray 4" and "dark slate grey 4" are
recognized color names.


File: plotutils.info,  Node: Metafiles,  Next: Auxiliary Software,  Prev: Color Names,  Up: Appendices

The Graphics Metafile Format
****************************

   A GNU graphics metafile, which is produced by raw `graph' or by any
other graphics application linked with raw `libplot', is a sort of
audit trail.  It contains a record of which `libplot' functions have
been called, together with their arguments.  That is, it is a sequence
of plotting commands, each of which may be followed by data.  Each
command is an `op code': a single ASCII character, indicating which
`libplot' function was called.  The data following the command are the
arguments of the function.  Arguments may be null-terminated ASCII
strings, or double precision floating point numbers in binary format,
or signed, two byte integers in binary format.  The last are used as a
means of storing integer arguments.

   For example, the `libplot' function call `move'(3,5), which moves
the graphics cursor to the position (3,5), could appear in a graphics
metafile as `m\000\003\000\005'.  The byte order of the binary
representation of the signed, two-byte integers is machine dependent,
so that on some machines, this command would appear as
`m\003\000\005\000'.  This machine dependence affects the
representation of all `libplot' functions that take integer arguments.

   The confusion over the proper representation for integers goes back
to the `plot(5)' format produced by non-GNU versions of `graph'.  GNU
graphics metafiles, which use an enhanced version of this format, may
include double precision floating point numbers as well as integers,
but the confusion over integer representations remains.  In fact it has
become slightly worse.  The two-byte representation described above is
no longer the default representation produced by GNU `libplot'.  By
default, integer arguments to `libplot' functions are now represented
in GNU metafiles as short integers.  On some machines a short integer
may occupy more than two bytes.

   There is also a portable (ASCII) version of GNU metafile format,
which is less confusing.  It is produced by raw `graph' when the `-O'
option is specified, and read by the GNU plot filters when the `-I'
option is specified.  In the portable version, the arguments to each
single-letter command are supplied in human readable form, separated by
spaces, and each argument list ends with a newline.  This
representation is acceptable because `libplot' functions include a
maximum of one string among their arguments, and this string may not
include a newline.  Moreover, the string must come last among the
arguments.

   The following table lists some of the op codes, i.e.,
single-character commands, followed by the name of the `libplot'
function they stand for.  All `libplot' functions have a corresponding
single-character command, with the exception of (1) the setup functions
`openpl' and `closepl', (2) the functions `labelwidth' and
`flabelwidth', which simply return the width of a text string, and
(3) the `pencolorname' and `fillcolorname' functions, which are mapped
to `pencolor' and `fillcolor' internally.

Op Code
     Function

`a'
     `arc'

`c'
     `circle'

`e'
     `erase'

`f'
     `linemod'

`l'
     `line'

`m'
     `move'

`n'
     `cont'

`p'
     `point'

`s'
     `space'

`t'
     `label'

The above are actually the op codes of the traditional `plot(5)' format.
They are also used in GNU metafiles, since the GNU metafile format is
compatible with it.  The op codes standing for the other functions in
`libplot' are too numerous to list.  They are defined in the file
`plot.h', which is distributed along with the GNU plotting utilities.


File: plotutils.info,  Node: Auxiliary Software,  Next: Acknowledgements,  Prev: Metafiles,  Up: Appendices

Obtaining Auxiliary Software
****************************

* Menu:

* idraw::	Obtaining the idraw drawing editor
* xfig::       	Obtaining the xfig drawing editor


File: plotutils.info,  Node: idraw,  Next: xfig,  Prev: Auxiliary Software,  Up: Auxiliary Software

How to get `idraw'
==================

   The `idraw' utility mentioned several times in this documentation is
a freely distributable interactive drawing editor for the X Window
System.  It may be used to edit the output of `graph-ps', or, in
general, the output of any application linked with the `libplotps'
version of `libplot'.

   The current version of `idraw' is maintained by Vectaport, Inc., and
is available from `http://www.vectaport.com'.  It is part of the
`ivtools' package, which is a framework for building custom drawing
editors.  `idraw' was originally part of the `InterViews' package,
developed by Stanford University and Silicon Graphics.  The
`InterViews' package is available at `ftp://interviews.stanford.edu'
but is no longer supported.  Retrieving the `ivtools' package instead
is recommended.

   Also available from `http://www.vectaport.com' is an enhanced
version of `idraw' called `drawtool'.  Unlike `idraw', `drawtool' can
import bitmapped graphics in PBM/PGM/PPM, TIFF, and X11 bitmap formats.


File: plotutils.info,  Node: xfig,  Prev: idraw,  Up: Auxiliary Software

How to get `xfig'
=================

   The `xfig' utility mentioned several times in this documentation is
a freely distributable interactive drawing editor for the X Window
System.  It may be used to edit the output of `graph-fig', or, in
general, the output of any application linked with the `libplotfig'
version of `libplot'.

   The current version is available in
`ftp://ftp.x.org/contrib/applications/drawing_tools/'.  It can import
graphics in GIF, X11 bitmap, and Postscript formats.  Accompanying the
editor is a package called `transfig', which allows `xfig' graphics to
be exported in many formats.  GIF, X11 bitmap, LaTeX, and Postscript
formats are supported.


File: plotutils.info,  Node: Acknowledgements,  Prev: Auxiliary Software,  Up: Appendices

Acknowledgements
****************

   Versions of `graph' and `plot' appeared in many early releases of
Unix, going at least as far back as the Version 7 distribution from
Bell Laboratories.  Supported devices in those days (c. 1980) included
200dpi electrostatic printer/plotters from Versatec and Varian, pen
plotters from Hewlett-Packard, Tektronix storage scopes, and early
graphics terminals.

   Rich Murphey <rich@lamprey.utmb.edu> wrote the first GNU versions of
`graph', `plot', and `spline', and the earliest documentation.  Richard
Stallman <rms@gnu.ai.mit.edu> further directed development of the
programs and provided editorial support for the documentation.  John
Interrante <interran@uluru.stanford.edu> generously provided the
`idraw' Postscript prologue now included in `libplotps', and helpful
comments.  The distribution, as it stood in 1991, was distributed under
the name `GNU graphics'.

   In 1995 Robert Maier <rsm@math.arizona.edu> took over development of
the package, and wrote the current, maximally device-independent,
standalone versions of `libplot'.  He also rewrote `graph' from
scratch, turning it into a real-time filter that would use the new
libraries.  He fleshed out `spline' too, by adding support for splines
in tension, periodicity, and cubic Bessel interpolation.

   Most development work on `ode' was performed by Nick Tufillaro
<nbt@reed.edu> in 1978-1994, on a sequence of platforms that extended
back to a PDP-11 running Version 4 Unix.  In 1997 Robert modified
Nick's 1994 version to agree with GNU conventions on coding and
command-line parsing, extended it to support the full set of special
functions supported by `gnuplot', and extended the exception handling.

   Many other people aided the development of the plotting utilities
package along the way.  The Hershey vector fonts now in `libplot' are
of course based on the characters digitized in the mid to late 1960's
by Allen V. Hershey.  Additional characters and/or marker symbols were
taken from the SLAC Unified Graphics System developed by Robert C.
Beach in the mid-1970's, and from the fonts designed by Thomas Wolff
<wolff@inf.fu-berlin.de> for Ghostscript.  Arthur Smith, formerly of
LASSP at Cornell, provided code for his `xplot' utility.  Ray Toy
<toy@rtp.ericsson.se> helped with the tick mark spacing code in `graph'
and was the first to incorporate GNU `getopt'.  Peter Karnow of URW and
Ken Turkowski of Apple <turk@apple.com> developed the `sagitta'
algorithm used in an extended form in `libplot' for drawing circular
and elliptic arcs.  Nelson Beebe exhaustively tested the package
installation process, and discovered many bugs.

   Robert Maier wrote the documentation, which now incorporates Nick
Tufillaro's `ode' manual.  Julie Sussmann checked over the
documentation for style and clarity.



Tag Table:
Node: Top884
Node: Introduction1682
Node: graph Examples7929
Node: Simple Examples8681
Node: Non-Square Plots20322
Node: Multiple Datasets22408
Node: Multiplotting28024
Node: Data Formats30852
Node: graph Invocation33207
Node: Plot Options33958
Node: Dataset Options45188
Node: Multiplot Options52873
Node: Raw graph Options54012
Node: Info Options54743
Node: Plot Filters55523
Node: Plot Filter Invocation55762
Node: Plot Filter Options57713
Node: libplot62459
Node: Programming65715
Node: Functions69096
Node: Setup Functions70258
Node: Attribute Functions72227
Node: Drawing Functions81126
Node: Mapping Functions90545
Node: Environment92537
Node: spline Examples94877
Node: spline Invocation101763
Node: ode107971
Node: Basic Math109243
Node: Simple ode Examples112115
Node: Additional ode Examples121048
Node: ode Invocation128027
Node: Diagnostics132070
Node: Numerical Error136193
Node: Running Time147494
Node: Input Language148823
Node: ODE Bibliography157232
Node: Appendices158243
Node: Text and Markers158682
Node: Text Fonts159390
Node: Text String Format168579
Node: Marker Symbols186663
Node: Color Names188660
Node: Metafiles189897
Node: Auxiliary Software193587
Node: idraw193862
Node: xfig194994
Node: Acknowledgements195746

End Tag Table
