Plotting Values

If you have huge amounts of numerical data to examine, a picture often says more than a thousand numbers. Therefore, DDD allows you to draw numerical values in nice 2-D and 3-D plots.

• Plotting Arrays: Plotting 1-D and 2-D arrays.
• Plot Appearance: Controlling the appearance.
• Scalars and Composites: Plotting simple values.
• Plotting Histories: Plotting the history of a variable.
• Printing Plots: Printing on paper.
• Entering Plotting Commands: Raw Gnuplot commands.
• Exporting Plot Data: Processing data outside of DDD
• Animating Plots: Visualizing dynamic behaviour.
• Customizing Plots: All at your leisure.

Node:Plotting Arrays, Next:Plot Appearance, Up:Plotting Values

Plotting Arrays

Basically, DDD can plot two types of numerical values:

• One-dimensional arrays. These are drawn in a 2-D

  Illegal HTML tag removed : x

  /

  Illegal HTML tag removed : y

  space, where

  Illegal HTML tag removed : x

  denotes the array index, and

  Illegal HTML tag removed : y

  the element value.

• Two-dimensional arrays. These are drawn in a 3-D

  Illegal HTML tag removed : x

  /

  Illegal HTML tag removed : y

  /

  Illegal HTML tag removed : z

  space, where

  Illegal HTML tag removed : x

  and

  Illegal HTML tag removed : y

  denote the array indexes, and

  Illegal HTML tag removed : z

  the element value.

To plot a fixed-size array, select its name by clicking mouse button 1 on an occurrence. The array name is copied to the argument field. By clicking the Plot button, a new display is created in the data window, followed by a new top-level window containing the value plot.

To plot a dynamically sized array, you must use an array slice (see Array Slices). In the argument field, enter

     

**Illegal HTML tag removed :** array

[

**Illegal HTML tag removed :** first

]@

**Illegal HTML tag removed :** nelems

     

where Illegal HTML tag removed : array is the name of the array to display, Illegal HTML tag removed : first is the index of the first element, and Illegal HTML tag removed : nelems is the number of elements to display. Then, click on Plot to start the plot.

To plot a value, you can also enter a command at the debugger prompt:

     graph plot 

**Illegal HTML tag removed :** expr

     

works like graph display Illegal HTML tag removed : expr (and takes the same arguments; see Creating Single Displays), but the value is additionally shown in the plot window.

Each time the value changes during program execution, the plot is updated to reflect the current values. The plot window remains active until you close it (via File => Close) or until the associated display is deleted.

Node:Plot Appearance, Next:Scalars and Composites, Previous:Plotting Arrays, Up:Plotting Values

Changing the Plot Appearance

The actual drawing is not done by DDD itself. Instead, DDD relies on an external gnuplot program to create the drawing.

DDD adds a menu bar to the Gnuplot plot window that lets you influence the appearance of the plot:

• The View menu toggles optional parts of the plot, such as border lines or a background grid.

• The Plot menu changes the

  Illegal HTML tag removed : plotting style

  . The 3-D Lines option is useful for plotting two-dimensional arrays.

• The Scale menu allows you to enable logarithmic scaling and to enable or disable the scale tics.
• The Contour menu adds contour lines to 3-D plots.

In a 3-D plot, you can use the scroll bars to change your view position. The horizontal scroll bar rotates the plot around the Illegal HTML tag removed : z axis, that is, to the left and right. The vertical scroll bar rotates the plot around the Illegal HTML tag removed : y axis, that is, up and down.

You can also resize the plot window as desired.

Node:Scalars and Composites, Next:Plotting Histories, Previous:Plot Appearance, Up:Plotting Values

Plotting Scalars and Composites

Besides plotting arrays, DDD also allows you to plot scalars (simple numerical values). This works just like plotting arrays--you select the numerical variable, click on Plot, and here comes the plot. However, plotting a scalar is not very exciting. A plot that contains nothing but a scalar simply draws the scalar's value as a Illegal HTML tag removed : y constant--that is, a horizontal line.

So why care about scalars at all? DDD allows you to combine multiple values into one plot. The basic idea is: if you want to plot something that is neither an array nor a scalar, DDD takes all numerical sub-values it can find and plots them all together in one window. For instance, you can plot all local variables by selecting Data => Display Local Variables, followed by Plot. This will create a plot containing all numerical values as found in the current local variables. Likewise, you can plot all numeric members contained in a structure by selecting it, followed by Plot.

If you want more control about what to include in a plot and what not, you can use display clusters (see Clustering). A common scenario is to plot a one-dimensional array together with the current index position. This is done in three steps:

1. Display the array and the index, using Display.
2. Cluster both displays: select them and choose Undisp => Cluster ().
3. Plot the cluster by pressing Plot.

Scalars that are displayed together with arrays can be displayed either as vertical lines or horizontal lines. By default, scalars are plotted as horizontal lines. However, if a scalar is a valid index for an array that was previously plotted, it is shown as a vertical line. You can change this initial orientation by selecting the scalar display, followed by Rotate.

Node:Plotting Histories, Next:Printing Plots, Previous:Scalars and Composites, Up:Plotting Values

Plotting Display Histories

At each program stop, DDD records the values of all displayed variables, such that you can "undo" program execution (see Undoing Program Execution). These display histories can be plotted, too. The menu item Plot => Plot history of () creates a plot that shows all previously recorded values of the selected display.

Node:Printing Plots, Next:Entering Plotting Commands, Previous:Plotting Histories, Up:Plotting Values

Printing Plots

If you want to print the plot, select File => Print Plot. This pops up the DDD printing dialog, set up for printing plots. Just as when printing graphs, you have the choice between printing to a printer or a file and setting up appropriate options.

The actual printing is also performed by Gnuplot, using the appropriate driver. Please note the following caveats related to printing:

• Creating FIG files requires an appropriate driver built into Gnuplot. Your Gnuplot program may not contain such a driver. In this case, you will have to recompile Gnuplot, including the line #define FIG in the Gnuplot term.h file.
• The Portrait option generates an EPS file useful for inclusion in other documents. The Landscape option makes DDD print the plot in the size specified in the Paper Size option; this is useful for printing on a printer. In Portrait mode, the Paper Size option is ignored.
• The Gnuplot device drivers for PostScript and X11 each have their own set of colors, such that the printed colors may differ from the displayed colors.
• The Selected Only option is set by default, such that only the currently selected plot is printed. (If you select multiple plots to be printed, the respective outputs will all be concatenated, which may not be what you desire.)

Node:Entering Plotting Commands, Next:Exporting Plot Data, Previous:Printing Plots, Up:Plotting Values

Entering Plotting Commands

Via File => Command, you can enter Gnuplot commands directly. Each command entered at the gnuplot> prompt is passed to Gnuplot, followed by a Gnuplot replot command to update the view. This is useful for advanced Gnuplot tasks.

Here's a simple example. The Gnuplot command

     set xrange [

**Illegal HTML tag removed :** xmin

:

**Illegal HTML tag removed :** xmax

]
     

sets the horizontal range that will be displayed to Illegal HTML tag removed : xmin...Illegal HTML tag removed : xmax. To plot only the elements 10 to 20, enter:

     gnuplot> 

**Illegal HTML tag removed :** set xrange [10:20]

     gnuplot> _
     

After each command entered, DDD adds a replot command, such that the plot is updated automatically.

Here's a more complex example. The following sequence of Gnuplot commands saves the plot in TeX format:

     gnuplot> 

**Illegal HTML tag removed :** set output "plot.tex"

 # Set the output filename
     gnuplot> 

**Illegal HTML tag removed :** set term latex

        # Set the output format
     gnuplot> 

**Illegal HTML tag removed :** set term x11

          # Show original picture again
     gnuplot> _
     

Due to the implicit replot command, the output is automatically written to plot.tex after the set term latex command.

The dialog keeps track of the commands entered; use the arrow keys to restore previous commands. Gnuplot error messages (if any) are also shown in the history area.

The interaction between DDD and Gnuplot is logged in the file ~/.ddd/log (see Logging). The DDD --trace option logs this interaction on standard output.

Node:Exporting Plot Data, Next:Animating Plots, Previous:Entering Plotting Commands, Up:Plotting Values

Exporting Plot Data

If you want some external program to process the plot data (a stand-alone Gnuplot program or the xmgr program, for instance), you can save the plot data in a file, using File => Save Data As. This pops up a dialog that lets you choose a data file to save the plotted data in.

The generated file starts with a few comment lines. The actual data follows in X/Y or X/Y/Z format. It is the same file as processed by Gnuplot.

Node:Animating Plots, Next:Customizing Plots, Previous:Exporting Plot Data, Up:Plotting Values

Animating Plots

If you want to see how your data evolves in time, you can set a breakpoint whose command sequence ends in a cont command (see Breakpoint Commands. Each time this "continue" breakpoint is reached, the program stops and DDD updates the displayed values, including the plots. Then, DDD executes the breakpoint command sequence, resuming execution.

This way, you can set a "continue" breakpoint at some decisive point within an array-processing algorithm and have DDD display the progress graphically. When your program has stopped for good, you can use Undo and Redo to redisplay and examine previous program states. See Undoing Program Execution, for details.

Node:Customizing Plots, Previous:Animating Plots, Up:Plotting Values

Customizing Plots

You can customize the Gnuplot program to invoke, as well as a number of basic settings.

• Gnuplot Invocation:
• Gnuplot Settings:

Node:Gnuplot Invocation, Next:Gnuplot Settings, Up:Customizing Plots

Gnuplot Invocation

Using Edit => Preferences => Helpers => Plot, you can choose the Gnuplot program to invoke. This is tied to the following resource:

Using Edit => Preferences => Helpers => Plot Window, you can choose whether to use the Gnuplot plot window (External) or to use the plot window supplied by DDD (builtin). This is tied to the following resource:

| The Gnuplot terminal type. Can have one of two values:

• If this is x11, DDD "swallows" the external Gnuplot output window into its own user interface. Some window managers, notably mwm, have trouble with swallowing techniques.

• Setting this resource to xlib (default) makes DDD provide a builtin plot window instead. In this mode, plots work well with any window manager, but are less customizable (Gnuplot resources are not understood).

  | | --- |

You can further control interaction with the external plot window:

Node:Gnuplot Settings, Previous:Gnuplot Invocation, Up:Customizing Plots

Gnuplot Settings

To change Gnuplot settings, use these resources:

See the Gnuplot documentation for additional commands.

Node:Examining Memory, Previous:Plotting Values, Up:Examining Data