reduce-historical/r36/help/pk-gplot.tex

\section{Gnuplot package}

\begin{Introduction}{GNUPLOT and REDUCE}

The GNUPLOT 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 X-windows, VGA screen, postscript, picTeX.
The REDUCE GNUPLOT package lets one use the GNUPLOT
graphical output directly from inside REDUCE, either for
the interactive display of curves/surfaces or for the production
of pictures on paper.

Note that this package may not be supported on all system
platforms.

For a detailed description you should read the GNUPLOT
system documentation, available together with the GNUPLOT
installation material from several servers by anonymous FTP.

The REDUCE developers thank the GNUPLOT people for their permission
to distribute GNUPLOT together with REDUCE.
\end{Introduction}

\begin{Concept}{Axes names}
Inside REDUCE the choice of variable names for a graph is completely
free. For referring to the GNUPLOT axes the names
X and Y for 2 dimensions, X,Y and Z for 3 dimensions are used
in the usual schoolbook sense independent from the variables of
the REDUCE expression.

\begin{Examples}
  plot(w=sin(a),a=(0 .. 10),xlabel="angle",ylabel="sine");
\end{Examples}

\end{Concept}

\begin{Type}{Pointset}
\index{plot}
A curve can be give as set of precomputed points (a polygon)
in 2 or 3 dimensions. Such a point set is a \nameref{list}
of points, where each point is a \nameref{list} 2 (or 3)
numbers. These numbers are interpreted as \name{(x,y)}
(or \name{x,y,z}) coordinates. All points of one set must have
the same dimension.

\begin{Examples}
 for i:=2:10 collect{i,factorial(i)};

\end{Examples}

Also a surface in 3d can be given by precomputed points,
but only on a logically orthogonal mesh: the surface is defined
by a list of curves (in 3d) which must have a uniform length.
GNUPLOT then will draw an orthogonal mesh by first drawing the
given lines, and second connecting the 1st point of the 1st curve
with the 1st point of the 2nd curve, that one with the 1st point
of the 3rd curve and so on for all curves and for all indexes.


\end{Type}


\begin{Command}{PLOT}
\index{graphics}\index{plot}
The command \name{plot} is the main entry for drawing a
picture from inside REDUCE.

\begin{Syntax}
\name{plot}\(\meta{spec},\meta{spec},...\)
\end{Syntax}

where \meta{spec} is a \meta{function}, a \meta{range} or an \meta{option}.

\meta{function}:

- an expression depending
on one unknown (e.g. \name{sin(x)} or two unknowns (e.g.
\name{sin(x+y)},

- an equation with a function on its right-hand
side and a single name on its left-hand side (e.g.
\name{z=sin(x+y)} where the name on the left-hand side specifies
the dependent variable.

- a list of functions:
if in 2 dimensions the picture should have more than one
curve the expressions can be given as list (e.g. \name{\{sin(x),cos(x)\}}).

- an equation with zero left or right hand side describing
   an implicit curve in two dimensions (e.g. \name{x**3+x*y**3-9x=0}).

- a point set: the graph can be given
as point set in 2 dimensions or a \nameref{pointset}  or pointset list
in 3 dimensions.

\meta{range}:

Each dependent and independent variable can be limited
to an interval by an equation where the left-hand side specifies
the variable and the right-hand side defines the \nameref{interval},
e.g. \name{x=( -3 .. 5)}.

If omitted the independent variables
range from -10 to 10 and the dependent variable is limited only
by the precision of the IEEE floating point arithmetic.

\meta{option}:

An option can be an equation equating a variable
and a value (in general a string), or a keyword(GNUPLOT switch).
These have to be included in the gnuplot command arguments directly.
Strings have to be enclosed in
string quotes (see \nameref{string}). Available options are:

\nameref{title}: assign a heading (default: empty)

\nameref{xlabel}: set label for the x axis

\nameref{ylabel}: set label for the y axis

\nameref{zlabel}: set label for the z axis

\nameref{terminal}: select an output device

\nameref{size}: rescale the picture

\nameref{view}: set a viewpoint

\name{(no)}\nameref{contour}: 3d: add contour lines

\name{(no)}\nameref{surface}: 3d: draw surface (default: yes)

\name{(no)}\nameref{hidden3d}: 3d: remove hidden lines (default: no)

\begin{Examples}
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}};\\
\\
on rounded;\\
w:=for j:=1:200 collect {1/j*sin j,1/j*cos j,j/200}$\\
plot w; \\
\end{Examples}

Additional control of the \name{plot} operation:
\nameref{plotrefine},
\nameref{plot_xmesh}, \nameref{plot_ymesh}, \nameref{trplot},
\nameref{plotkeep}, \nameref{show_grid}.

\end{Command}

\begin{Command}{PLOTRESET}
The command \name{plotreset} closes the current GNUPLOT windows.
The next call to \nameref{plot} will create a new one. \name{plotreset}
can also be used to reset the system status after technical problems.

\begin{Syntax}
\name{plotreset};
\end{Syntax}
\end{Command}


\begin{Variable}{title}
\index{plot}
\nameref{plot} option:
Assign a title to the GNUPLOT graph.

\begin{Syntax}
\name{title} = \meta{string}
\end{Syntax}
\begin{Examples}
title="annual revenue in 1993"\\
\end{Examples}
\end{Variable}

\begin{Variable}{xlabel}
\index{plot}
\nameref{plot} option:
Assign a name to to the x axis (see \nameref{axes names}).

\begin{Syntax}
\name{xlabel} = \meta{string}
\end{Syntax}
\begin{Examples}
xlabel="month"\\
\end{Examples}
\end{Variable}

\begin{Variable}{ylabel}
\index{plot}
\nameref{plot} option:
Assign a name to to the x axis (see \nameref{axes names}).

\begin{Syntax}
\name{ylabel} = \meta{string}
\end{Syntax}
\begin{Examples}
ylabel="million forint"\\
\end{Examples}
\end{Variable}

\begin{Variable}{zlabel}
\index{plot}
\nameref{plot} option:
Assign a name to to the z axis (see \nameref{axes names}).

\begin{Syntax}
\name{zlabel} = \meta{string}
\end{Syntax}
\begin{Examples}
zlabel="local weight"\\
\end{Examples}
\end{Variable}

\begin{Variable}{terminal}
\index{plot}
\nameref{plot} option:
Select a different output device. The possible values here
depend highly on the facilities installed for your GNUPLOT
software.

\begin{Syntax}
\name{terminal} = \meta{string}
\end{Syntax}
\begin{Examples}
terminal="x11"\\
\end{Examples}
\end{Variable}

\begin{Variable}{size}
\index{plot}
\nameref{plot} option:
Rescale the graph (not the window!) in x and y direction.
Default is 1.0 (no rescaling).

\begin{Syntax}
\name{size} = "\meta{sx},\meta{sy}"
\end{Syntax}
where \meta{sx},\meta{sy} are floating point number not too
far from 1.0.
\begin{Examples}
size="0.7,1"\\
\end{Examples}
\end{Variable}

\begin{Variable}{view}
\index{plot}
\nameref{plot} option:
Set a new viewpoint by turning the object around the x and then
around the z axis (see \nameref{axes names}).

\begin{Syntax}
\name{view} = "\meta{sx},\meta{sz}"
\end{Syntax}
where \meta{sx},\meta{sz} are floating point number representing
angles in degrees.
\begin{Examples}
view="30,130"\\
\end{Examples}
\end{Variable}

\begin{Switch}{contour}
\index{plot}
\nameref{plot} option:
If \name{contour} is member of the options for a 3d \nameref{plot}
contour lines are projected to the z=0 plane
(see \nameref{axes names}). The absence of contour lines
can be selected explicitly by including \name{nocontour}. Default
is \name{nocontour}.
\end{Switch}


\begin{Switch}{surface}
\index{plot}
\nameref{plot} option:
If \name{surface} is member of the options for a 3d \nameref{plot}
the surface is drawn. The absence of the surface plotting
can be selected by including \name{nosurface}, e.g. if
only the \nameref{contour} should be visualized. Default is \name{surface}.
\end{Switch}


\begin{Switch}{hidden3d}
\index{plot}
\nameref{plot} option:
If \name{hidden3d} is member of the options for a 3d \nameref{plot}
hidden lines are removed from the picture. Otherwise a
surface is drawn as transparent object. Default is
\name{nohidden3d}. Selecting \name{hidden3d} increases the
computing time substantially.
\end{Switch}

\begin{Switch}{PLOTKEEP}
\index{plot}
Normally all intermediate data sets are deleted after terminating
a plot session. If the switch \name{plotkeep} is set \nameref{on},
the data sets are kept for eventual post processing independent
of REDUCE.
\end{Switch}

\begin{Switch}{PLOTREFINE}
\index{plot}
In general \nameref{plot} tries to generate smooth pictures by evaluating
the functions at interior points until the distances are fine
enough. This can require a lot of computing time if the
single function evaluation is expensive. The refinement is
controlled by the switch \name{plotrefine} which is \nameref{on}
by default. When you turn it \nameref{off} the functions will
be evaluated only at the basic points (see \nameref{plot_xmesh},
\nameref{plot_ymesh}).
\end{Switch}

\begin{Variable}{plot_xmesh}
\index{plot}
The integer value of the global variable \name{plot_xmesh}
defines the number of initial function evaluations in x
direction (see \nameref{axes names}) for \nameref{plot}. For 2d graphs additional
points will be used as long as \nameref{plotrefine} is \name{on}.
For 3d graphs this number defines also the number of mesh lines
orthogonal to the x axis.
\end{Variable}

\begin{Variable}{plot_ymesh}
\index{plot}
The integer value of the global variable \name{plot_ymesh}
defines for 3d  \nameref{plot} calls the number of function evaluations in y
direction (see \nameref{axes names}) and the number of mesh lines
orthogonal to the y axis.
\end{Variable}

\begin{Switch}{SHOW_GRID}
\index{plot}
The grid for localizing an implicitly defined curve in \nameref{plot}
consists of triangles. These are computed initially equally distributed
over the x-y plane controlled by \nameref{plot_xmesh}. The grid is
refined adaptively in several levels. The final grid can be visualized
by setting on the switch \name{show_grid}.
\end{Switch}


\begin{Switch}{TRPLOT}
\index{plot}
In general the interaction between REDUCE and GNUPLOT is performed
as silently as possible. However, sometimes it might be useful
to see the GNUPLOT commands generated by REDUCE, e.g. for a
postprocessing of generated data sets independent of REDUCE.
When the switch \name{trplot} is set on all GNUPLOT commands will
be printed to the standard output additionally.
\end{Switch}