Basic plotting

This page covers basic Warp plot functions using the pygist graphics package. Generally, a Warp user should, where possible, use already developed diagnostic scripts to generate plotsand modify/extend existing scripts as appropriate. But when developing new scripts, extending existing scripts, diagnosing problems, and special situations, a basic understanding of plotting functions can be useful. Below we cover Viewing/Exporting Plots both interactively within Warp and outside of Warp, basic X-Y Plots, and Particle and Contour Plots.

Viewing/Exporting Plots

Here we elaborate on basic plot information already part covered as a simple example in the How To on Running Warp. In this example, commands contained within a simple script plot.py are executed to provide an example of simple interactive and non-interactive Warp runs.

Consider the Warp script plot.py which contains the following commands before execution of any plot commands:

# Read in Warp

from warp import *

# Setup graphics output

setup()

When plot.py is interactively read into python with:

% python -i plot.py

or non-interactively with:

% python plot.py

Then via the setup() command, Warp will generate a cgm output format file plot.000.cgm in the directory which python is run. The file will contain plots made as the script is run and during the interactive session. cgm stands for Computer Graphics Metafile which is a open standard format for 2d vector graphics. 000 is an automatically generated output number whichis incremented by one from the last value each time the script is run. An associated log file plot.000.cgmlog with the same output number is also automatically generated. The plots in plot.000.cgm will be stored in the sequence they were generated (possibly overlaid) in the balance of the script. When running interactively, the user can see subsequent plots as they are made by opening a graphics window with the following command:

winon()

This opens an X-window where subsequent plot frames created are displayed. Interactive plotting can be particularly useful for debugging and gaining an understanding of what the simulation is doing. Multiple graphics windows can be created using the same winon command, passing in a new window number.

winon(winnum=1)

Note that the first window created will have the default window number of 0. Multiple windows are useful for comparing plot frames interactively.

The output cgm file plot.001.cgm can be viewed using the gist cgm viewer with the command:

% gist plot.000.cgm

The cgm file will be opened and can be displayed frame-by-frame in an X-window using gist viewer commands. Typically, the first several frames of the cgm file will display information about the run (the frames are created during the generate). The rest of the frames contain plots generated by the balance of the script. Note that gist will only be able to display frames that had been written to the file when it is opened. If more plot frames are created after the file was opened, then gist would need to be restarted to view these new frames.

With the cursor in the graphics window, there are various keyboard commands for scrolling through and interacting with gist.

f - Forward one frame

b - Backward one frame

10f - Forward 10 frames

10b - Backward 10 frames

F - Forward n frames

B - Backward n frames

10n - Set n to 10 (10 is the default)

r - Redraw current frame

g - Goto first frame

G - Goto last frame

s - Send current frame to output device (see below for more info)

q - Quit

Alternatively, these same commands can be entered at gist prompt. Type help for more information.

If there are multiple plot files in a directory (eg., plot.000.cgm, plot.001.cgm, plot002.cgm ....) from multiple runs and gist is used to view output from an earlier run, as one advances through the frames past the end of the file gist will view frames from the other files in the directory. Care should be taken so this feature does not cause confusion.

The gist viewer can send selected frames to new files. This is controlled by setting the output device, which can be either ps, eps, or cgm. For example, the following will set the output device to the be plot.ps file, using postscript.

gist> ps plot.ps

The currently displayed frame is sent to the file by typing "s" in the graphics window or at the gist prompt. The file will contain all of the frames sent to it. Similarly, the cgm command will set the output device to a cgm file. This technique is useful for extracting a limited number of frames out of (potentially large!) simulation output files for long-term archiving of limited data in the original cgm format. The eps command can be used for creating encapsulated postscript, but note that the file can contain only one frame.

Postcript output generated using the ps command in gist is a vector graphic which can be converted to other vector formats such as pdf and fig, or bitmap formats such as png, jpg, gif, etc. Bitmap formats may be desireable for particle scatter plots which may contain much data making vector format graphics potentially large. Detailed graphics conversion procedures vary widely with the software tools and operating system used and it is not practical to cover them here. The Warp development team has found the following software tools to be particularly useful for graphics manipulations:

pstoedit Unix program to convert vector format graphics from one type to another (often ps to fig for use with xfig)

xfig Free vector graphic editor using "fig" format that the export to many formats. Used in conjunction with pstoedit.

Acrobat Adobe commercial vector (pdf) graphics editor

ImageMagick Graphics viewer with extensive conversion capabilities

Documentation can be found on the linked sites and via online searches. The free software tools in this list can typically be loaded with standard package managers such as yum on Linux/Unix operating systems. Add-on package managers such as HomeBrew and MacPorts can be used to load the free software tools on Mac OSX.

Line Plots

Here we overview line plotting which also serves to illustrate the basic operation of the pygist graphics package within Warp. This extends the How To on Running Warp which was based on a simple line plot.

First, we define example data vectors using numpy. x is a uniformly spaced mesh between 0 and 1. y and y2 are created from x.

n = 10

x = linspace(0.,1.,n+1)

y = x

y2 = x**2

First, make a simple line plot of the straight line.

plg(y,x)

ptitles("Plot Title","x","y","Line plot example")

fma()

This generates the graphic as shown in Fig. 1. Here, ptitles() is called to label the plot and fma() (short for "frame advance") is called to clear the frame so it is ready for the next plot. The call to fma() also sends the plot to the output cgm file. Note that when Warp is exited, if fma() had not been called, then the last frame produced will not be written to the output file and will be lost. Labels can be eliminated in ptitles() using None in any blank field before the desired label to while keeping the correct placement order, i.e., ptitles(None,"x") will produce only an x-axis label.

Fig. 1. Example line plot with x- and y-axis labels and a plot title.

Multiple plots can be overlaid on a single frame, allowing the user to build up intricate composite diagnostics from existing scripts. Several line plots can be overlaid as show here.

plg(y,x,type="dash")

plg(y2,x,color=red)

ptitles("Plot Title","x","y","Overlaid line plots")

fma()

The result is shown in Fig. 2.

Fig. 2. Example overlay line plot with axis and title labels and changed line colors and types to extend the basic presentation in Fig. 1.

In the above example, the type of the line is set to "dash" and the parabola is drawn in red to illustrate use of options. Common settings for type and color include:

type = "none", "solid", "dash", "dot", "dashdot", "dashdotdot", or 0 - 5, respectively.

color = black, red, yellow, green, cyan, blue, magenta, white

Numerous other keyword options can be applied with details provided by doc(plg).

The limits command is used to set the extent of the plot, as shown in the example here.

plg(y2,x)

limits(-1.,2.,-0.5,1.5)

ptitles("Plot Title","x","y","limits example")

fma()

The result is shown in Fig. 3. The syntax of limits is:

limits(xmin,xmax,ymin,ymax)

Any of the min/max settings can be set to "e" (including the quotes) to use the extreme value of the data plotted. Note that the x-y ordering in limits() is opposite to the ordering in plg(). The ymin and ymax can be omitted if only setting the x values.

Fig. 3. Example plot with modified limits to extend the presentation in Figs. 1 and 2.

Particle and Contour Plots

To be added.