This material is based upon work supported by the following organizations and programs:
The Intense Pulsed Neutron Source Division of Argonne National Laboratory, contract No. W-31-109-ENG-38. ( Accordingly, the U.S. Government retains a non exclusive, royalty-free license to publish or reproduce the published form of this contribution, or allow others to do so, for U.S. Government purposes. )
The National Science Foundation, Grant No. DUE-9351943.
The University of Wisconsin - Stout Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the above named organizations.
Permission to use, copy, modify, and distribute this software and its documentation for non-commercial purposes without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the author or the above named organizations not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.
The author and the above named organizations make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. It is provided with no support and without obligation to assist in its use, correction, modification, or enhancement.
THE AUTHOR AND ABOVE NAMED ORGANIZATIONS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PURPOSE. IN NO EVENT SHALL THE AUTHOR OR THE ABOVE NAMED ORGANIZATIONS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTUOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
A. System Requirements
B. Directory Structure
C. Unix Installation
D. VMS Installation
E. Sample Data
A. Use of Zoom
B. Axis Types
C. Rebinned Data
D. Popup Valuators
E. X Axis Range
F. Color Scales
G. Horizontal Graph
H. Mask Files
I. Printing
TOF_VIS is a highly interactive program for viewing time of flight neutron diffraction data. It displays a collection of diffraction spectra simultaneously in the form of an image. Although the principal use of this may be to provide an overview of the data from many different detectors, it should also be useful to display changes in the spectrum of a sample as temperature, pressure, time, etc. are varied. TOF_VIS presents three views of a set of spectra. The main "view" shows the set of spectra as an image in which each row of the image corresponds to one spectrum. The rows of the image can be ordered by "ID" ( that is an integer index 1..N ) or by the angle between the neutron beam and the detector. The columns of the image correspond to uniform steps in time, energy, wavelength, "d" or "Q". The other two "views" of the data are conventional graphs of data obtained from vertical or horizontal cuts across the image. Specifically, the user can drag the mouse pointer across the image to select a row and column of the image. The selected spectrum is displayed as a graph across the bottom of the window. The graph of the spectrum can be displayed either as raw time of flight data with the boundaries of the time channels merely transformed to the appropriate units, or as data that has been re-sampled ( "rebinned" ) into equal size intervals of the appropriate units (t, E, lambda, d or Q ). The third view is a graph of data from the column of the image that appears along the left edge of the image. This graph displays counts in the "x" direction and either "ID", angle or "Q" in the "y" direction. All of the views can be easily "zoomed" to get a closer look at fine details in the data. Also, the time, energy, wavelength, "d" and "Q" values corresponding to points in the image or on the graph of a spectrum are computed and displayed as the mouse is dragged over the window. Each of the three views of the data can be printed to a Postscript printer or file.
The TOF_VIS program itself is split into three levels: an interface layer, translation layer and an application layer, as shown in the diagram below. The interface layer constructs the various motif widgets, sets up callback routines that respond to user input, etc. The translation layer consists largely of callback routines that are called in response to user input. The callback routines call on the application layer to carry out the requested action and then display the results in widgets created in the interface layer. The application layer is independent of MOTIF and provides the basic functionality of the application. For example, the application produces graphs and images as arrays of values, independent of how those are ultimately displayed.
TOF_VIS:
___________________________________________
| INTERFACE LAYER (Motif Dependent) |
| |
| tof_vis.c |
| PrintDialog.c |
|___________________________________________|
| TRANSLATION LAYER (Motif Dependent) |
| |
| tof_vis_trans.c |
| |
|___________________________________________|
| APPLICATION LAYER (Independent of Motif) |
| |
| tof_vis_app.c |
| NS_SpecTools.c |
| tof_vis_calc.c |
| tof_vis_file_access.c |
| tof_vis_plot.c |
|___________________________________________|
The TOF_VIS program as shown above, rests on several other more general purpose units. First, the details of accessing data from IPNS data files are handled by the IPNS_FileManager unit.
IPNS_FILEMANAGER:
___________________________________________
| IPNS specific data file access |
| |
| IPNS_FileManager.c |
| |
|___________________________________________|
Many of the low level Motif programming details are handled by routines from the MMOTIF_TOOLS unit. This unit includes convenience routines for several commonly used Motif capabilities such as creating a main window and menus. In addition it includes "pseudo" widgets for displaying images and graphs and popup valuators. In addition, convenience routines for dealing with 8-plane pseudo color are included.
MMOTIF_TOOLS:
___________________________________________
| General Purpose Motif Utilities |
| |
| MMT_Image.c |
| MMT_Graph.c |
| MMT_Valuator.c |
| MMT_MainWindow.c |
| MMT_Menus.c |
| MMT_Help.c |
| MMT_Utilities.c |
| MMT_Color.c |
| MMT_ColorUtilites.c |
|___________________________________________|
| Internal support routines |
| |
| MMT_DCursorArea.c |
| MMT_CoordArea.c |
| MMT_CallbackList.c |
|___________________________________________|
Finally, low-level convenience routines for allocating and freeing 1, 2 and 3 dimensional arrays in "C" are provided by the ArrayTools unit. This is designed to facilitate work with arbitrary sized arrays and the construction of routines that process arbitrary size arrays.
MATH_TOOLS:
___________________________________________
| General Purpose Array Allocate/Free |
| |
| ArrayTools.c |
|___________________________________________|
V. CUSTOMIZATION
The TOF_VIS program itself is designed to be quite generic. Specifically, it is intended to deal with a collection of time-of-flight spectra for which the appropriate flight path length, angle, list of times, etc., are known. It is assumed that the path length, angle and times are "coordinated". For example, if the times are adjusted to do "time focusing" it is assumed that the lengths provided in the data file are the "virtual" lengths for which the spectra are focused. Also, if the data is from a spectrometer, it is assumed that the input energy is available and that the lengths provided are sample to detector lengths. For a diffractometer, it is assumed that the lengths are the total flight path length. Within this context, the data examined by TOF_VIS can be raw data from a collection of detectors, or could be data from a range of angular groups on an instrument like GLAD. Finally, it could even be a set of spectra gathered as some physical parameter such as temperature is varied. In order to view such data from other sources, it will be necessary to replace the unit "tof_vis_file_access.c" with a unit that reads in the required information. This unit should be quite easy to replace. The following routines must be recoded:
InitFileAccess OpenDifFileCloseDifFileGetRunInfoGetDetInfoGetIncidentEnergyGetTOFSpectrumGetTOFTimeFieldTypeGetTimes
InitFileAccess()
OpenDifFile( *f_name )
CloseDifFile( f_handle )
GetRunInfo( f_handle, *title, *data_type, *n_ids,
*n_histogram, *n_tf_types )
GetDetInfo( f_handle, histogram, id, *angle,
*path_length )
GetIncidentEnergy( f_handle, histogram, *in_energy )
GetTOFSpectrum(
f_handle, histogram, id, *spectrum )
GetTOFTimeFieldType( f_handle, histogram, id, *tf_type )
GetTimes( f_handle, histogram, tf_type, *times )
In order to demonstrate a very simple recoding and use of this unit, a clear text format data file "demo_data.txt" is included. This data file may be read if the program is compiled and linked with the "demo_file_access.c" routine using the command file "build_demo". The format is NOT intended to provide a really useful format, but is merely intended to show another very simple file access unit that is independent of the IPNS run file format. The text file format and demo_file_access.c unit assumes that the routines will be called in a certain sequence. IT IS NOT EXPECTED THAT THIS SEQUENCE WILL BE MAINTAINED IN FUTURE VERSIONS. It would be preferable to replace tof_vis_file_access.c with another direct access file mechanism that will allow access to that data in any order and allow spectra to be read more than once, etc. Further details on these routines is included in the header file: ../TOF_VIS/include/tof_vis_file_access.h