Back to files

This is the README file for yPlot, a Yorick front-end to PLPlot.

PREAMBLE

yPlot is meant to be a useful tool in creating scientific plots of both draft and publication quality quickly and efficiently. That said, it should be realised that most of this usefulness comes from Yorick and PLPlot, so thanks to their respective creators and maintainers. Most of what yPlot can do is due to the fact that David Munroe wrote Yorick to be extensible by linking external object files to the Yorick interpreter. Thanks!

yPlot facilities

yPlot implements most of the public API of the (extensive) capabilities of the PLPlot library from Yorick. That is, as demonstrated by the doc/x??.i examples, virtually all postscript results generated by the PLplot x??c examples can be mimicked exactly with a very easy-to-learn syntax. Also, some extra yplot functions are added for reading data from files. More functions not exercised by the extensive set of demos can easily be added on request or contribution.

So, yPlot can do the following in the hands of even an inexperienced user: o Access to all the capabilities of Yorick. Do all your data generation, interpretation and plotting from one package. o Linear plots
o Log-log plots, with any variations of log and linear axes possible o 3D surface and mesh plots (there is a difference, really ;-) o 3D line and scatter
o 3D shaded surface
o Contour plots
o Shade plots (with either solid or pattern fill of the shaded regions using either color map0 (discrete colours) or colour map1 (continuous colours). o Grid lines
o Lots of symbols and stroked fonts to choose from, all scalable o Full control over boxes drawn, captions, fonts and placement of labels o Speed: A yPlot plot finishes in about 3 times that of the corresponding compiled C version. Huh? Doesn't sound very fast, until you factor in the compiling time and development time (which can be VERY long if your C is not quite up to scratch. Like ours :-) o Fast development due to the the interpreted nature of yPlot o Lots of output devices, including X11, Postscript, Laserjet printers, PNG, JPEG and PLPlot metafiles for later rendering. o PLUS: a tutorial and reference manual that demonstrates most of yPlot's capabilities with explanations every step of the way!

Note on required software packages/versions

yplot 1.1.2 only works with Yorick 1.5 and PLplot 5.2.1(or later CVS version). You also need python (1.5 or greater) to build the documentation.

Note on command-line processing.

If your script includes the plparseopts, PL_PARSE_FULL; command, then the command-line (exclusive of -batch filename) is parsed for the standard PLplot options such as -dev and -o. Use the -h option to see all the possibilities.

Note on Landscape and Portrait plotting

Versions of PLplot prior to 5.0.4 defaulted to seascape mode (upside-down landscape), but PLplot 5.0.4 and subsequent versions (now PLplot 5.2.1) default to landscape mode. To get this same default use the yplotl command. However, PLplot-5.2.1 also has a portrait option (invoked with the -portrait command-line option) for the ljii, ljiip, ps, psc, and pstex devices which involves a 90 deg clockwise rotation from landscape plus aspect-ratio swap. This option is automatically invoked by the yplot command or you can use yplotl -portrait instead. Because portrait mode is now available from PLplot, there is no longer any reason to maintain separate yplot portrait-mode drivers so those have been eliminated.

DEMOS

The doc subdirectory contains a large number of examples to show off yPlot. After installing, run these with e.g. yplot -batch x01.i -dev psc -o temp.ps and view those (good-looking) results with gv temp.ps. Alternatively, all examples are built using make -f Makefile.build. (See the INSTALL file for what you have to do before you can run this command.)

DEVICES

To get a current list of these for your system run one of the demos without the -dev command-line option. The DEVICES file was generated this way from a fairly completely configured PLplot-5.2.1 system, but generate your own list to get an exact list for your system.

Note that if you create a plplot metafile "plmeta", you can change it to any of the other available devices using the plrender command from the plplot package. (plrender -h gives help with this command.)

IMPORTANT DOCUMENTATION

ANNOUNCE Announcement of yPlot.

README This file.

INSTALL How to build and install yplot, yplotl, the demos, and the documentation.

CHANGES Important changes to the API

DEVICES List of possible devices. Run any demo without the device specified to get an exact list of what is available on your system.

doc/*.i yPlot scripts for demos.

doc/ytut.[tex, ps] Detailed tutorial for yPlot. Parts of this tutorial which used to be out-of-date are exactly on track with the latest yplot because they are based directly and automatically on the Yorick-style documentation within yplot_body.i and on existing demo files. The tutorial figures are generated automatically as well from certain of the demo scripts. So any changes to yplot_body.i or the demo scripts get immediately reflected in the tutorial. (Ah the magic of Makefiles and python parsing scripts.)

yPlot itself. While running yplot or yplotl interactively you can get help on all yplot and yorick commands by issuing help, commandname.

doc/yplot.doc Listing generated by yorick mkdoc command of all yPlot help.

info yorick gives extensive help on yorick

http://plplot.sourceforge.net/resources/docbook-manual/ gives the latest PLplot-5.2.1 documentation.

Bugs and patches and support

"Correct them, send them, and don't expect any" ;-)

Seriously

If you find any bugs, do the following: o Try really hard to find out if it isn't your own fault. o If you are able, try and correct the problem in either read.c, pplot.c or yplot_body.i or the Makefile.build.in or configure.in files. (Those and the documentation are our only contribution actually.) o Send us a description of the problem and any diffs (see man diff) you may come up with. o We will try our best to solve the problem or incorporate your fix.

That said, yPlot has been in daily use for both of us for some time without any problems and it is considered to be quite stable.

If you would like to do any work on extending yPlot, go ahead make our month! Look at the files read.c, pplot.c and yplot_body.i for examples, and Makefile_build.in and configure.in for how it is put together. It really isn't very complicated, even we could understand it...

Please...

If you find yPlot useful, please drop us an e-mail. It helps justify the time we spent developing yPlot when we should have been doing serious research.

Alan W. Irwin <irwin@beluga.phys.uvic.ca> Conrad Steenberg <conrad@hep.caltech.edu> 2003 May 14.