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.
mmGraph may be started either by selecting the mmGraph button on mmLaunch or from the command line via
tclsh oommf.tcl mmGraph [standard options] [-net <0|1>]
Input to mmGraph may come from either a file in the ODT format, or when -net 1 (the default) is active, from a client application (typically a running solver). 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 a data set close message is received from a client application, or when requested by the user using the mmGraph Options|Break menu option.
Unlike mmDataTable, mmGraph internally stores the data sent to it. These 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.)
Graphs are constructed by selecting any one item off the X-axis menu, and any number of items off the Y1-axis and Y2-axis menus. The y1-axis is marked on the left side of the graph; the y2-axis on the right. 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, all the axis menus are 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-axes labels are the measurement unit of the first corresponding y-axis item selected.
The Options|Configure... dialog box allows the user to override default settings. To change the graph title, simply enter the desired title into the Title field. To set the axis labels, deselect the Auto Label option in this dialog box, and fill in the X Label, Y1 Label and Y2 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.
The size of the margin surrounding the plot region is computed automatically. Larger margins may be specified by filling in the appropriate fields in the Margin Requests section. Units are pixels. Requested values smaller than the computed (default) values are ignored.
As mentioned earlier, mmGraph stores in memory 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. If curves are selected off both the y1 and y2 menus, then a horizontal line in the key separates the two sets of curves, with the labels for the y1 curves on top.
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.
The width of the lines may be changed by the usual method of local customization. The default setting in config/options.tcl is
which makes the line segments 2 pixels wide. This can be set to any positive integer value. Curves will be rendered more quickly, especially on Windows, if curve_width is set to 1.Oc_Option Add mmGraph Ow_GraphWin curve_width 2
A few other controls are also available only through the mouse. If the mouse pointer is positioned over a drawn item in the graph, holding down the left mouse button will bring up the coordinates of that point, with respect to the y1-axis. Similarly, depressing the right mouse button, or alternatively holding down the shift key while pressing the left mouse button will bring up the coordinates of the point with respect to the y2-axis. 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 or right mouse button.
The menu selection File|Exit terminates the mmGraph application. The menu Help provides the usual help facilities.
The axes menus are configured based on incoming data. As a result, these menus are initially empty. If a graph widget is scheduled to receive data only upon control point or stage done 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. 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 they arrive.