% introduction.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: introduction.tex 1282 2012-07-29 23:30:47Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Introduction}

\label{ch:introduction}

\section{What is Pyxplot?}

Pyxplot is a multi-purpose graph plotting tool, scientific scripting language,
vector graphics suite, and data processing package.  Its interface is designed
to make common tasks -- e.g., plotting labelled graphs of data -- accessible
via short, simple, intuitive commands.

But these commands also take many optional settings, allowing their output to
be fine-tuned into styles appropriate for printed publications, talks or
websites.  Pyxplot is simple enough to be used without prior programming
experience, but powerful enough that programmers can extensively configure and
script it.

\noindent{\bf A scientific scripting language}

Pyxplot doesn't just plot graphs. It's a scripting language in which variables
can have physical units. Calculations automatically return results in an
appropriate unit, whether that be kilograms, joules or lightyears.  \Datafile s
can be converted straightforwardly from one set of units to another. Meanwhile
Pyxplot has all the other features of a scripting language: flow control and
branching, string manipulation, complex data types, an object-oriented class
structure and straightforward file I/O.  It also supports vector and matrix
algebra, can integrate or differentiate expressions, and can numerically solve
systems of equations.

\noindent{\bf A vector graphics suite}

The graphical canvas isn't just for plotting graphs on. Circles, polygons and
ellipses can be drawn to build vector graphics. Colors are a native object type
for easy customisation. For the mathematically minded, Pyxplot's canvas
interfaces cleanly with its vector math environment, so that geometric
construction is easy.

\noindent{\bf A data processing package}

Pyxplot can interpolate data, find best-fit lines, and compile histograms. It
can Fourier transform data, calculate statistics, and output results to new
\datafile s. Where fine control is needed, custom code can be used to process
every data point in a file.

\section{Compatibility with \gnuplot}

Pyxplot's plotting interface is very similar to that of \gnuplot: the commands
used for plotting simple graphs in the two programs are virtually identical.
Gnuplot users will have a head start with Pyxplot -- simple \gnuplot\ scripts
often work in Pyxplot with minimal modification -- although the syntax used
for advanced plotting tasks often differs. Although Pyxplot's programming and
mathematical environment is hugely extended over \gnuplot's to provide a
scripting language and vector graphics environment, we have followed the
latter's preference for short simple command line syntax.

\section{The structure of this manual}

This manual serves both as a tutorial guide to Pyxplot, and also as a reference
manual. Part~I provides a step-by-step tutorial and overview of Pyxplot's
features, including numerous worked examples. Part~II provides a detailed
survey of Pyxplot's plotting and vector graphics commands. Part~III provides an
alphabetical reference to all of Pyxplot's commands, mathematical functions and
plotting options.  Finally, the appendices provide information which is likely
to be of more specialist interest.

\section{An introductory tour}

This section provides an overview of the wide range of tasks for which Pyxplot
can be used. Detailed explanations of the syntax of Pyxplot commands will
follow in later chapters, but most of the examples here will work if entered
directly at a Pyxplot command prompt.

\subpart{The mathematical environment}

Pyxplot's mathematical environment comes with many standard functions built-in.
To see a list of them\footnote{See also Chapter~\ref{ch:function_list}.}, type

\begin{verbatim}
show functions
\end{verbatim}

The {\tt show} command is Pyxplot's interactive documentation system; to obtain
a list of things that can be shown type

\begin{verbatim}
show
\end{verbatim}

\noindent Pyxplot is an object-orientated language, and its built-in functions
live in a module called {\tt defaults}.  Its members may be listed by {\tt
print}ing the module object. 

\begin{verbatim}
print defaults
\end{verbatim}

Taking as an example the built-in function {\tt log10(x)}, it can be evaluated
as in almost any other programming language. The {\tt defaults} module
is special in that its functions are always accessible to the user's namespace:

\vspace{3mm}
\input{fragments/tex/intro_print1.tex}
\vspace{3mm}

\noindent This function returns numerical data, but Pyxplot has other data
types too.  For example, the {\tt primeFactors} function returns a list:

\vspace{3mm}
\input{fragments/tex/intro_print2.tex}
\vspace{3mm}

\noindent The {\tt rgb(r,g,b)} function returns a color object, which can be
used in Pyxplot's vector graphics commands:

\vspace{3mm}
\input{fragments/tex/intro_print3.tex}
\vspace{3mm}

\noindent and the {\tt time.fromUnix(t)} function returns a date object from a
Unix time:

\vspace{3mm}
\input{fragments/tex/intro_print4.tex}
\vspace{3mm}

Many commonly-used physical constants are built into Pyxplot's physics module,
{\tt phy}. For example, the speed of light:

\vspace{3mm}
\input{fragments/tex/intro_print5.tex}
\vspace{3mm}

\noindent Numbers in Pyxplot have {\bf physical units}, and hence the speed of
light is displayed in km/s. If you would rather know how many miles light
travels in a year, you can change the display unit, here making use of the fact
that the variable {\tt ans} is always set to the result of the last
calculation:

\vspace{3mm}
\input{fragments/tex/intro_print6.tex}
\vspace{3mm}

\noindent It is easy to use Pyxplot as a {\bf desktop calculator} to solve many
problems which would conventionally need careful conversion between physical
units. For example:

\begin{itemize}
\item What is $80^\circ$F in Celsius?

\vspace{3mm}
\input{fragments/tex/intro_tempConvert.tex}
\vspace{3mm}

\item How long does it take for light to travel from the Sun to the
Earth?\footnote{The astronomical unit (AU) is a unit used by astronomers, equal
to the average distance of the Earth from the Sun.}

\vspace{3mm}
\input{fragments/tex/intro_earthDistance.tex}
\vspace{3mm}

\item What wavelength of light corresponds to the ionisation energy of hydrogen
(13.6\,eV)?\footnote{The electron volt (eV) is a unit of energy used by
physicists.}

\vspace{3mm}
\input{fragments/tex/intro_Hionisation.tex}
\vspace{3mm}

\item What is the escape velocity of the Earth?\footnote{The Earth radius and
Earth mass are defined as units in Pyxplot.}

\vspace{3mm}
\input{fragments/tex/intro_escapeVelocity.tex}
\vspace{3mm}
\end{itemize}

\subpart{Graph plotting}

The simplest way to plot a graph in Pyxplot is simply to follow the {\tt plot}
command with the name of a function to be plotted, e.g.:

\begin{verbatim}
plot sin(x)
\end{verbatim}

\noindent If a \datafile\ is to be plotted, its filename is put in place of a
named function. In this example the fifth column of a \datafile\ is plotted
against the second, including only those \datapoint s where the fourth column
is larger than two:

\begin{verbatim}
plot 'data.dat' using 2:5 select $4>2
\end{verbatim}

In the example below, three Bessel functions are plotted over specified
horizontal and vertical ranges:

\begin{verbatim}
plot [0:10][-0.5:1] besselJ(0,x), besselJ(1,x), besselJ(2,x)
\end{verbatim}
\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_intro_bessel}
\end{center}

\noindent With a little additional configuration, it is possible to produce
three-dimensional plots like this (this example is taken from
Section~\ref{sec:surfaces}; see Example~\ref{ex:surface-sinc}):

\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_surface_sinc}
\end{center}

\noindent It is also possible to produce colormaps with custom color scales;
this is documented in full in Section~\ref{sec:colormaps}.  Pyxplot includes
functions for converting wavelengths of light into colors; they are used here
to create a color map of the electromagnetic spectrum:

\begin{center}
\includegraphics[width=7cm]{examples/eps/ex_spectrum_1}
\end{center}

\noindent This pair of images demonstrates RGB color mixing (see
Example~\ref{sec:colmap_custom}):

\begin{center}
\includegraphics[width=6cm]{examples/eps/ex_spectrum_colmix1}
\includegraphics[width=6cm]{examples/eps/ex_spectrum_colmix2}
\end{center}

\subpart{Generating data tables}

Pyxplot can output tables of data to disk, using a similar syntax to that used
for plotting graphs. The data can either be sampled from functions, or read in
from another \datafile:

\begin{verbatim}
tabulate tan(x)
\end{verbatim}

\noindent A common application of the {\tt tabulate} command is filter or
re-format the contents of \datafile s. For example, the command below takes
only the third and seventh columns out of a \datafile, and converts the latter
from degrees into radians:

\begin{verbatim}
tabulate 'data.dat' using 3:$7*unit(deg)/unit(rad)
\end{verbatim}

\noindent The same effect could be achieved by setting radians as the default
unit of angle:

\begin{verbatim}
set unit of angle radians
tabulate 'data.dat' using 3:$7*unit(deg)
\end{verbatim}

\noindent More sophisticated data processing is also possible; this example
produces a histogram of the values in the fourth column of a datafile, and then
outputs that histogram as a new \datafile:

\begin{verbatim}
histogram h() 'data.dat' using 4
tabulate h(x)
\end{verbatim}

\subpart{Solving equations}

Pyxplot can solve systems of equations numerically; the following example
evaluates $\int_{0\,\mathrm{s}}^{2\,\mathrm{s}} x^2\,\mathrm{d}x$:

\vspace{3mm}
\input{fragments/tex/intro_integration.tex}
\vspace{3mm}

\noindent The {\tt solve} command can be used to solve systems of simultaneous equations, such as this system with two variables:

\vspace{3mm}
\input{fragments/tex/intro_simultaneousEq.tex}
\vspace{3mm}

\noindent The {\tt minimise} and {\tt maximise} commands find the extrema of functions; here they are used to find the minimum of the function $\cos(x)$ closest to $x=0.5$:

\vspace{3mm}
\input{fragments/tex/intro_cosMin.tex}
\vspace{3mm}

All of the examples shown so far have used only real numbers, but Pyxplot can
also perform algebra on complex numbers. By default, evaluation of {\tt
sqrt(-1)} throws an error -- the emergence of complex numbers is often an
indication that a calculation has gone wrong -- but complex arithmetic can be
enabled by typing\indcmd{set numerics complex}

\vspace{3mm}
\input{fragments/tex/intro_complex1.tex}
\vspace{3mm}

\noindent Many of the mathematical functions which are built into Pyxplot can take complex arguments, for example

\vspace{3mm}
\input{fragments/tex/intro_complex2.tex}
\vspace{3mm}

\subpart{Vector graphics}

Pyxplot's graph-plotting canvas can also be used for drawing general vector graphics, using simple commands such as:

\begin{verbatim}
box from -8,-4 to 8,4 with fillcolor green
text "Pyxplot" at 2,3
arrow from 0,0 to -4,2
line from -5,0 to 5,0
\end{verbatim}

\noindent These commands are described in detail in
Chapter~\ref{ch:vector_graphics}. They interface neatly to the vector data type
in Pyxplot's mathematical environment, to ease geometric construction. Thus, it
is quite possible for mathematically-minded users to multiply transformation
matrices with position vectors on the graphics canvas to calculate where
objects should be drawn. The following example uses a rotation matrix to draw a
big arrow at angle $\theta$ to the vertical:

\begin{verbatim}
rotate(a) = matrix( [[cos(a),-sin(a)], \
                     [sin(a), cos(a)] ] )
pos = vector(0,5)*unit(cm)
theta = 30*unit(deg)
arrow from 0,0 to rotate(theta)*pos with linewidth 3
\end{verbatim}

\section{License}

This manual and the software which it describes are both copyright \copyright\
Dominic Ford~2006--2012 and Ross Church~2008--2012. They are distributed under
the GNU General Public License (GPL) Version~2, a copy of which is provided in
the {\tt COPYING} file in this distribution.\index{General Public
License}\index{license} Alternatively, it may be downloaded from the web, from
the following location:\\ \url{http://www.gnu.org/copyleft/gpl.html}.

\section{Spelling conventions}

Throughout this manual, US English is used. However, where spelling differs
between US~and UK~English, Pyxplot recognises both variants. For example, where
the word \texttt{color} appears in Pyxplot syntax, it may also be spelt
\texttt{colour}; \texttt{minimize} may also be spelt \texttt{minimise};
\texttt{gray} may also be spelt \texttt{grey}; \texttt{neighbor} may also be
spelt \texttt{neighbour}; etc.

\section{Acknowledgments}

Pyxplot builds on ideas from several pre-existing open-source software
projects. We like \gnuplot's simple and intuitive interface, and Pyxplot's
command syntax is intentionally very similar, to the point of backwards
compatibility in many cases. Even when designing the entirely new parts of
Pyxplot's syntax, we have followed \gnuplot's preference for short simple
command-line syntax.  Early versions of Pyxplot utilised the PyX\index{PyX}
graphics library for Python, and we have borrowed many ideas from it in our new
output engine.

Several people have contributed code to Pyxplot. Michael Rutter provided us 
with a copy of his public domain code for converting bitmap images into
PostScript, which we used in the implementation of the {\tt image} command and
the {\tt colormap} plot style. Matthew Smith provided C implementations of the
Airy functions and the Riemann zeta function for general complex inputs, and
helped test Pyxplot's mathematical environment. Zolt\'an V\"or\"os worked on
our development team from 2010 until 2011.  John Walker has published public
domain code implementing RGB rendering of the electromagnetic spectrum, which
we use in the {\tt colors.\-wave\-length()} function.

We would also like to thank all the users who have got in touch with us by
email since Pyxplot was first released on the web in~2006. Your feedback and
suggestions have been gratefully received.

Final thanks go to our team of alpha testers, without whose work Pyxplot would
doubtless still contain many more bugs.  Especial thanks go to Rachel Holdforth
and Stuart Prescott.