                        _       _      PYXPLOT
 _ __  _   ___  ___ __ | | ___ | |_    Version 0.9.2
| '_ \| | | \ \/ / '_ \| |/ _ \| __|   19/09/2012
| |_) | |_| |>  <| |_) | | (_) | |_ 
| .__/ \__, /_/\_\ .__/|_|\___/ \__|   Copyright (C) 2006-2012 Dominic Ford
|_|    |___/     |_|                                 2008-2012 Ross Church

For documentation and more information, see <http://www.pyxplot.org.uk>.

-----

1. INTRODUCTION

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.

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.  Datafiles
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.

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.

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
datafiles. Where fine control is needed, custom code can be used to process
every data point in a file.

Examples of the graphical output produced by Pyxplot can be found on the
Pyxplot website: <http://www.pyxplot.org.uk/>.


2. SYSTEM REQUIREMENTS

Pyxplot works on most UNIX-like operating systems. We have tested it under
Linux, Solaris and MacOS X, and believe that it should work on other similar
POSIX systems. We regret that it is not available for Microsoft Windows, and
have no plans for porting it at this time.

It requires that the following software packages (not included) be installed:

- fftw                       (version 2 or, preferably, 3+)
- gcc and make
- Ghostscript
- The Gnu Scientific Library (version 1.10+)
- ImageMagick
- LaTeX                      (version 2e)
- libpng                     (version 1.2+)
- libxml2                    (version 2.6+)
- zlib

It is also strongly recommended that the following software packages be
installed:

- cfitsio -- required for Pyxplot to be able to plot datafiles in FITS format.
- Ghostview (or ggv) -- required for Pyxplot to be able to display plots live
  on the screen; Pyxplot remains able to generate image files on disk without
  it. Alternatively, the set viewer within Pyxplot allows a different
  postscript viewer to be used.
- gunzip -- required for Pyxplot to be able to plot compressed datafiles in .gz
  format.
- The Gnu Readline Library (version 5+) -- required for Pyxplot to be able to
  provide tab completion and command histories in Pyxplot's interactive
  command-line interface.
- libkpathsea -- required to efficiently find the fonts used by LaTeX.
- wget -- required for Pyxplot to be able to plot datafiles directly from the
  Internet.

Debian and Ubuntu users can find the above software in the following packages:

fftw3-dev, gcc, ghostscript, gv, imagemagick, libc6-dev, libcfitsio3-dev,
libgsl0-dev, libkpathsea-dev, libpng12-dev, libreadline-dev, libxml2-dev, make,
texlive-latex-extra, texlive-latex-recommended, texlive-fonts-extra,
texlive-fonts-recommended, wget, zlib1g-dev.

These packages may be installed from a command prompt by typing, all on one
line:

sudo apt-get install fftw3-dev gcc ghostscript gv imagemagick libc6-dev libcfitsio3-dev libgsl0-dev libkpathsea-dev libpng12-dev libreadline-dev libxml2-dev make texlive-latex-extra texlive-latex-recommended texlive-fonts-extra texlive-fonts-recommended wget zlib1g-dev

Users of MacOS X can find the above software in the following MacPorts packages:

cfitsio, fftw-3, ghostscript, gsl-devel, gv, ImageMagick, libpng, libxml2,
readline-5, texlive, wget, zlib.

It may then be necessary to run the command

export C_INCLUDE_PATH=/opt/local/include

before running the configure script below.


3. INSTALLATION FROM SOURCE ARCHIVE

First, download the required archive can be downloaded from the front page of
Pyxplot website -- <http://www.pyxplot.org.uk>. It is assumed that the packages
listed above have already been installed; if they are not, you will need to
either install them yourself, if you have superuser access to your machine, or
contact your system administrator.

* Unpack the distributed .tar.gz:

tar xvfz pyxplot_0.9.0.tar.gz
cd pyxplot

* Run the installation script:

./configure
make

* Finally, start Pyxplot:

./bin/pyxplot


3A. SYSTEM-WIDE INSTALLATION

Having completed the steps described above, Pyxplot may be installed
system-wide by a superuser with the following additional step:

sudo make install

By default, the Pyxplot executable installs to /usr/local/bin/pyxplot.  If
desired, this installation path may be modified in the file Makefile.skel, by
changing the variable USRDIR in the first line to an alternative desired
installation location.

Pyxplot may now be started by any system user, simply by typing:

pyxplot



4. FURTHER INFORMATION

Full documentation can be found in doc/pyxplot.tex , or in doc/pyxplot.pdf
after installation. This document is alternatively available from the Pyxplot
website: <http://www.pyxplot.org.uk/>.

----
Dominic Ford
Ross Church

