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 app/oommf/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.
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.
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. To change the default y-axis label, deselect all y-axis items and select a different first item.
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 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 last command on the options menu is Options|Key, which toggles the key (legend) display on and off. The key may also be repositioned by dragging with the left mouse button.
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 equilibrium 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.