Overview
The application mmGraph provides a data display service similar to
that of mmDataTable. The usual
data source is a running solver, but rather than the textual output
provided by mmDataTable, mmGraph produces 2D line plots.
mmGraph also stores the data it receives, so it can produce
multiple views of the data and can save the data to disk. Postscript
output is also supported.
Launching
mmGraph may be started either by selecting the mmGraph
button on mmLaunch or from the command
line via
tclsh oommf.tcl mmGraph [-console] [-nonet]The
-nonet
option disables the socket
server portion of mmGraph, in which case data may only be input
from a file.
Inputs
Input to mmGraph may come from either a file in the
ODT format,
or from a client application (typically a running solver). (The
latter is disabled by the -nonet
command line option.) The
File|Open... dialog box is used to select an input file.
Receipt of data from client applications is the same as for
mmDataTable. In either
case, input data are appended to any previously held data.
Curve breaks (i.e., separation of a curve into disjoint segments) are recorded in the data storage buffer via curve break records. These records are generated whenever a Table Start or a Table End record is read from an ODT file, when an empty data record is received from a client application, or when requested by the user using the mmGraph Options|Break menu option.
Outputs
Unlike mmDataTable, mmGraph internally stores the data sent to it. This data may be written to disk via the File|Save As... dialog box. If the file specified already exists, then mmGraph output is appended to that file. The output is in the tabular ODT format. The data are segmented into separate Table Start/Table End blocks across each curve break record.
By default, all data currently held by mmGraph is written, but the Save: Selected Data option presented in the File|Save As... dialog box causes the output to be restricted to those curves currently selected for display. In either case, the graph display limits do not affect the output.
The save operation writes records that are held by mmGraph at the time the File|Save As... dialog box OK button is invoked. Additionally, the Auto Save option in this dialog box may be used to automatically append to the specified file each new data record as it is received by mmGraph. The appended fields will be those chosen at the time of the save operation, i.e., subsequent changing of the curves selected for display does not affect the automatic save operation. The automatic save operation continues until either a new output file is specified, the Options|Stop autosave control is invoked, or mmGraph is terminated.
The File|Print... dialog is used to produce a Postscript file of the current graph. On Unix systems, the output may be sent directly to a printer by filling the Print to: entry with the appropriate pipe command, e.g., |lpr. (The exact form is system dependent.)
Controls
Graphs are constructed by selecting any one item off the
X-Axis menu, and any number of items off the Y-Axis menu.
Either of these menus may be detached by selecting the dashed rule
at the top of the list. Sample results are shown in the figure at the
start of this section.
When mmGraph is first launched, the axis menus are both empty. They are dynamically built based on the data received by mmGraph. By default, the graph limits and labels are automatically set based on the data. The x-axis label is set using the selected item data label and measurement unit (if any). The y-axis label is the measurement unit of the first y-axis item selected.
The Options|Configure... dialog box allows the user to override the default settings. To set the axis labels, deselect the Auto Label option in this dialog box, and fill in the X Label and Y Label fields as desired. The axis limits can be set in a similar fashion. In addition, if an axis limit is left empty, a default value (based on all selected data) will be used.
As mentioned earlier, mmGraph stores all data it receives. Over the course of a long run, the amount of data stored can grow to many megabytes. This storage can be limited by specifying a positive (> 0) value for the Point buffer size entry in the Options|Configure... dialog box. The oldest records are removed as necessary to keep the total number of records stored under the specified limit. A zero value for Point buffer size is interpreted as no limit. (The storage size of an individual record depends upon several factors, including the number of items in the record and the version of Tcl being used.) Data erasures may not be immediately reflected in the graph display.
At any time, the point buffer storage may be completely emptied with the Options|clear Data command. The Options|stop Autosave selection will turn off the auto save feature, if currently active. Also on this menu is Options|Rescale, which autoscales the graph axis limits from the selected data. This command ignores but does not reset the ``Auto Scale'' settings in the Options|Configure... dialog box. The Options| Break item inserts a curve break record into the point buffer, causing a break in each curve after the current point. This option may be useful if mmGraph is being fed data from multiple sources.
The Options|Key selection toggles the key (legend) display on and off. The key may also be repositioned by dragging with the left mouse button.
The last command on the options menu is Options|Smooth. If smoothing is disabled, then the data points are connected by straight line segments. If enabled, then each curve is rendered as a set of parabolic splines, which do not in general pass through the data points. This is implemented using the -smooth 1 option to the Tcl canvas create line command; see that documentation for details.
Two other controls are also available only through the mouse. If the mouse pointer is positioned over a drawn item in the graph, holding down any mouse button will bring up the coordinates of that point. The coordinates displayed are the coordinates of a point on a drawn line, which are not necessarily the coordinates of a plotted data point. (The data points are plotted at the endpoints of each line segment.) The coordinate display is cleared when the mouse button is released.
One vertical and one horizontal rule (line) are also available. Initially, these rules are tucked and hidden against the left and bottom graph axes, respectively. Either may be repositioned by dragging with the left mouse button.
The menu selection File|Exit terminates the mmGraph application. The menu Help provides the usual help facilities.
Details
The X-Axis and Y-Axis menus are configured based on incoming
data. As a result, both menus are initially empty. If a graph widget
is scheduled to receive data only upon control point events in the
solver, it may be a long time after starting a problem in the solver
before the graph widget can be configured. Because mmGraph keeps
all data up to the limit imposed by the Point buffer size, data
loss is usually not a problem. Of more importance is the fact that
automatic data saving can not be set up until the first
data point is received. As a workaround, the solver initial state may
be sent interactively as a dummy point to initialize the graph widget
axes menus. (You may turn off the Interactive schedule connection
after sending this data point.) Select the desired quantities off the
axes menus, and use the Options|clear Data command to remove
the dummy point from mmGraph's memory. The File|Save
As... dialog box may then be used--with the Auto Save option
enabled--to write out an empty table with proper column header
information. Subsequent data will be written to this file as it
arrives.