\documentstyle[11pt,reduce]{article}
\date{}
\title{GNUPLOT Interface for REDUCE\\Version 3}
\author{Herbert Melenk \\
Konrad--Zuse--Zentrum f\"ur Informationstechnik Berlin \\
E--mail: Melenk@sc.zib--berlin.de}
\begin{document}
\maketitle
\index{GNUPLOT package}
\section{Introduction}
The GUNPLOT system provides easy to use graphics output
for curves or surfaces which are defined by
formulas and/or data sets. GNUPLOT supports
a great variety of output devices
such as \verb+X-windows+, \verb+SUN tools+,
\verb+VGA screen+, \verb+postscript+, \verb+pic+ \TeX.
The {\small REDUCE} GNUPLOT package lets one use the GNUPLOT
graphical output directly from inside {\small REDUCE}, either for
the interactive display of curves/surfaces or for the production
of pictures on paper.
{\small REDUCE} supports GNUPLOT 3.2. For most systems GNUPLOT binaries
are delivered together with {\small REDUCE}. However, this is a
basic set only. If you intend to use more facilities of the GNUPLOT
system or if your {\small REDUCE} has not been equipped with
GNUPLOT binaries you should pick up the full GNUPLOT file tree
from a server, e.g.
\begin{itemize}
\item dartmouth.edu (129.170.16.4)
\item monu1.cc.monash.edu.au (130.194.1.101)
\item irisa.irisa.fr (131.254.2.3)
\end{itemize}
Under UNIX {\small REDUCE} evaluates the environment variable
$gnuplot$; if this variable has been set, {\small REDUCE} redirects
the GNUPLOT calls to the directory described there. Otherwise the
binaries are expected in the directory $\$reduce/plot$.
\section{Incompatibilities}
In contrast to the previous {\small REDUCE} GNUPLOT package
this version computes all data points inside REDUCE and
passes them to GNUPLOT as a data file.
This simplifies the usage of the GNUPLOT package
and reduces some incompatibilities and restrictions.
\section{Loading GNUPLOT}
If on your computer the {\small REDUCE} GNUPLOT package
has been installed with autoload, you can call the command
\verb+PLOT(...)+ directly from any {\small REDUCE} session;
otherwise enter once per session
\begin{verbatim}
load_package gnuplot;
\end{verbatim}
\section{Command PLOT}
The \verb+PLOT(...)+ command can have a variable number of
parameters:
\begin{itemize}
\item A functions to plot; a function can be
\begin{itemize}
\item an expression with one unknown, e.g. $u*sin(u)**2$
\item an expression with two unknowns, e.g.
$u*sin(u)**2+sqrt(v)$
\item an equation with a symbol on the left-hand side
and an expression with one or two unknowns on the
right-hand side, e.g.// $dome=1/(x**2+y**2)$
\item a list of points in 2 or 3 dimensions
e.g. \\ $\{0,0\},\{0,1\},\{1,1\}\}$ representing
a curve,
\item a list of lists of points in 2 or 3 dimensions
e.g.\\ $\{\{0,0\},\{0,1\},\{1,1\}\}
\{0,0\},\{0,1\},\{1,1\}\}\}$
representing a family of curves.
\end{itemize}
\item A range for a variable; this has the form\\
$variable=(lower\_bound\, . . \, upper\_bound)$ where
$lower\_bound$ and $upper\_bound$ must be expressions which
evaluate to numbers. If no range is specified the
default ranges for independent variables are $(-10\,\,..\,\,10)$
and the range for the dependent variable is set to
maximum number of the GNUPLOT executable (using double
floats on most IEEE machines and single floats under DOS).
\item A GNUPLOT option, either as fixed keyword,
e.g.\ $hidden3d$ or as equation e.g.\ $term=pictex$;
free texts such as titles and labels such be enclosed in
string quotes.
\end{itemize}
Please note that a blank has to be inserted between a number
and a dot - otherwise the REDUCE translator will be mislead.
If a function is given as an equation the left-hand side
is mainly used as label for the axis of the dependent variable.
In two dimensions more than one function expressions can be given
which are drawns into one picture; however,
all these have to use the same independent variable name.
One of the functions can be a point set or a point set list.
Normally all functions and point sets are plotted by
lines; only if functions and point sets are drawn into
one picture the point set is drawn by points.
The functional expressions are evaluated in $rounded$ mode.
This is done automatically - it is not necessary to turn
on rounded mode explicitly.
Examples:
\begin{verbatim}
plot(cos x);
plot(s=sin phi,phi=(-3 .. 3));
plot(sin phi,cos phi,phi=(-3 .. 3));
plot (cos sqrt(x**2 + y**2),x=(-3 .. 3),y=(-3 .. 3),hidden3d);
plot {{0,0},{0,1},{1,1},{0,0},{1,0},{0,1},{0.5,1.5},{1,1},{1,0}};
% parametric: screw
on rounded;
w:=for j:=1:200 collect {1/j*sin j,1/j*cos j,j/200}$
plot w;
% parametric: globe
dd:=pi/15$
w:=for u:=dd step dd until pi-dd collect
for v:=0 step dd until 2pi collect
{sin(u)*cos(v), sin(u)*sin(v), cos(u)}$
plot w;
\end{verbatim}
The following GNUPLOT options are supported:
\begin{itemize}
\item $title=name$: the title (string) is put on top
of the picture.
\item axes labels: $xlabel="text1"$, $ylabel="text2"$, and for
surfaces $zlabel="text3"$. If omitted the axes are labeled
by the independent and dependent variable names from the
expression. Note that the axes names $x$label, $y$label and
$z$label here are used in the usual sense, $x$ for the
horizontal and $y$ for the vertical axis under 2-d and
$z$ for the perpendicular axis under 3-d -- these names
do not refer to the variable names used in the expressions.
\begin{verbatim}
plot(1,X,(4*X**2-1)/2,(X*(12*X**2-5))/3,
x=(-1 .. 1), ylabel="L(x,n)",
title="Legendre Polynomials");
\end{verbatim}
\item $terminal=name$: redirect output to device $name$.
Every installation uses a default terminal as output
device; some installations support additional
devices such as printers; consult your local
GNUPLOT installation material for details.
If the GNUPLOT set terminal command allows
additional parameters you have to form the full
value set as string in {\small reduce};
\item $size="s_x,s_y"$: rescale the graph (not the
window) where $s_x$ and $s_y$ are scaling
factors for the size in x or y
direction. Defaults are $s_x=1,x_z=1$.
Note that scaling factors greater than one
often will cause the picture to be too big for
the window.
\begin{verbatim}
plot(1/(x**2+y**2),x=(0.1 .. 5),
y=(0.1 .. 5), size="0.7,1");
\end{verbatim}
\item $view="r_x,r_z"$: set viewpoint for 3 dimensions
by turning the object around the x or z axis;
the values are degrees (integers).
Defaults are $r_x=60,r_z=30$.
\begin{verbatim}
plot(1/(x**2+y**2),x=(0.1 .. 5),
y=(0.1 .. 5), view="30,130");
\end{verbatim}
\item $contour$ resp $nocontour$: in 3 dimensions an
additional contour map is drawn (default: $nocontour$)
\item $surface$ resp $nosurface$: in 3 dimensions the
surface is drawn resp suppressed (default: $surface$).
\item $hidden3d$: hidden line removal in 3 dimensions.
\end{itemize}
\section{Mesh generation}
Per default the functions are computed at predefined
mesh points: the ranges are divided by $plot\_xmesh$ resp
$plot\_ymesh$, which are initially set to 20. These are
share variables and you can modify them globally for your
session by assigning different positive integer values.
Note that these values cannot be set in the plot command directly and
that the names $plot\_xmesh$ and $plot\_ymesh$ are
builtin and have to be used even if the unknowns of your
expressions have different names.
For two dimensions the given mesh is adaptively
smoothed when the curves are too coarse, especially
if singularities are present. On the other hand
refinement can be rather time consuming if used with
complicated expressions. You can turn it off by
$OFF$ $PLOTREFINE$. At singularities the graph is
interrupted.
In three dimensions no refinement is possible as surfaces
can be drawn only with a fixed grid. In the case
of a singularity the near neighbourhood is
tested; if a point there allows a function evaluation, its
clipped value used instead, otherwise a zero is inserted.
When plotting surfaces in three dimensions you have the
option of hidden line removal. Because of an error in
Gnuplot 3.2 with "hidden3d" the axes cannot be labelled
correctly; therefore they arn't labelled at all. Hidden line
removal is not available with point lists.
\section{GNUPLOT operation}
The command verb+PLOTRESET;+ deletes the current GNUPLOT output
window. The next call to verb+PLOT+ then will open a new one.
If GNUPLOT is invoked directly by an output pipe (UNIX and Windows),
an eventual error in the GNUPLOT data transmission might cause GNUPLOT to
quit. As {\small REDUCE} is unable to detect the broken pipe, you
have to reset the plot system by calling the
command \verb+PLOTRESET;+ explicitly. Afterwards new graphic output
can be produced.
Under DOS Windows 3.1 GNUPLOT has a text and a graph window.
If don't want to see the text window, iconify it and
activate the option ``update wgnuplot.ini" from the
graph window system menu - then the present screen layout
(including the graph window size) will be saved and the text
windows will com up iconified in future. You also can select
some more features there and so tailor the gaphic output.
Before you terminate {\small REDUCE} you should terminate the
graphic window by calling verb+PLOTRESET;+.
If you terminate {\small REDUCE} without deleting the
GNUPLOT windows before, use the command button from the
GNUPLOT text window - it offers an exit function.
\section{Saving GNUPLOT command sequence}
If you want to use the internal GNUPLOT command sequence
more than once (e.g. for producing a picture for a publication),
you best set
$ON \,\, TRPLOT,PLOTKEEP$;
$TRPLOT$ causes all GNUPLOT commands
to be written additionally to the actual
{\small REDUCE} output. Normally the data files are
erased after calling GNUPLOT, however with $PLOTKEEP$ on
the files are not erased.
\section{Direct Call of GNUPLOT}
GNUPLOT has many facilities which are not accessed by
the operators and parameters described above. Therefore
genuine GNUPLOT commands can be sent by {\small REDUCE}.
Please consult the GNUPLOT manual for the available
commands and parameters. The general syntax for a GNUPLOT call
inside {\small REDUCE} is
$gnuplot(<cmd>,<p_1>,<p_2> \cdots)$
where $<cmd>$ is a command name and $<p_1>,<p_2> \cdots$
are the parameters, inside {\small REDUCE} separated by
commas. The parameters are evaluated by
{\small REDUCE} and then transmitted to GNUPLOT in
GNUPLOT syntax. Usually a drawing is built by a
sequence of commands which are buffered
by {\small REDUCE} or the operating
system. For terminating and activating them use the {\small REDUCE}
command $plotshow;$. Example:
\begin{verbatim}
gnuplot(set,polar);
gnuplot(set,noparametric);
gnuplot(plot,x*sin x);
plotshow;
\end{verbatim}
Note that GNUPLOT restrictions with respect to variable
and function names have to be taken into account when
using this type of operation.
\end{document}