TOF_VIS USER MANUAL
Aug. 30. 1995 ( revised Jan. 16, 1997 )
(C) Copyright 1995-1997

II. INSTALLATION

A. System Requirements:

To build this software, the following are required:

• the X Window system with at least an 8-bit color graphics display
• OSF/MOTIF version 1.2 or later
• an ANSI C compiler ( GNU gcc, DEC C, etc. )
  

If hard copy output is desired the following are also required:

• a Fortran 77 compiler (GNU g77, DEC Fortran etc., f2c will NOT work)
• PGPLOT ( A freely available plotting package, available via FTP from astro.caltech.edu (131.215.240.1) )

TOF_VIS has been compiled and tested on the following systems:

• DEC ALPHA running VMS
• DEC ALPHA running OSF/1
• DEC VAX running VMS
• DEC MIPS running ULTRIX
• PC/AT Clone running LINUX ( a.out and elf )

Previous versions have been tested on

• HP 9000 running HP/UX
• PC/AT Clone running FreeBSD

and the current version should work on these systems as well.

The changes needed to move it to a different platform have been largely to modify the source to use the proper include files and then link with the correct libraries on the new system.

B. Directory Structure

To install TOF_VIS, first unpack the source tree in some directory, say <TOF>. The <TOF> directory will have five subdirectories: MATH_TOOLS, FILE_READ, MMOTIF_TOOLS, TOF_VIS and SAMPLE_DATA. Each of these directories contains components of TOF_VIS, as given below:

• MATH_TOOLS -- contains general purpose routines for allocating and freeing 1, 2 and 3 dimensional arrays of various data types.
• MMOTIF_TOOLS -- contains general purpose routines to make building MOTIF programs easier.
• FILE_READ -- contains special purpose routines to access data files, in the form of IPNS "run" files. This unit will not be needed if other data file formats are used.
• TOF_VIS -- contains the TOF_VIS application itself.
• SAMPLE_DATA -- contains a few sample data sets.

Each of these directories (other than SAMPLE_DATA) contains a source ( .../src ) subdirectory with the source code to compile. To facilitate this process on UNIX systems, a "make" file is provided. For VMS, a command file is provided.

C. UNIX Installation

To compile TOF_VIS on UNIX, first, set the following environment variables to indicate which compilers to use, where various include and library files are, etc. Specifically set:

• CC ( specifying which C compiler to use )
• CFLAGS ( specifying any special flags to pass to the C compiler)
• LIB_DIRS ( specifying where X/MOTIF, PGPLOT and other libraries are IF they are not found using the default library paths )
• INC_DIRS ( specifying where X/MOTIF, PGPLOT and other header files are IF they are not found using the default include paths )
• F77 ( specifying which FORTRAN compiler to use )
• F77_FLAGS ( specifying any special flags to pass to the FORTRAN compiler )

NOTE: It is very important to set the F77 environmental correctly. In particular on a LINUX system F77 will default to a script calling f2c, and f2c will NOT work properly.

For example:

1. setenv CC gcc
2. setenv CFLAGS -Wall
3. setenv LIB_DIRS "-L/usr/MY/lib -L/usr/YOUR_LIB/lib"
4. setenv INC_DIRS "-I/usr/MY_LIB/include -I/usr/YOUR_INCLUDES/include"
5. setenv F77 g77
6. setenv F77_FLAGS -Wall
   

It should now suffice to type 'make' in the top level directory. This should construct the needed libraries and place the executable in .../TOF_VIS/src/tof_vis. A few sample data sets are in .../SAMPLE_DATA.

If this does not work, it may help to run the individual Makefiles in the subdirectories from the subdirectories. Several sets of utilities can be compiled and tested separately. Doing so will help to track down the problem, which will most likely be some problem with specifying directories, compilers and/or compiler flags.

To separately compile and test: do:

MATH_TOOLS

1. cd MATH_TOOLS
2. make
3. cd tests
4. make test
   

MMOTIF_TOOLS

1. cd MMOTIF_TOOLS
2. make
3. cd tests
4. make test

( now try to run some of the test programs )

FILE_READ

1. cd FILE_READ
2. make

( there is not an easy to use test for this unit )

Once these units on which TOF_VIS is built have been successfully compiled and tested, try to build "tof_vis" itself. First try to compile it without printing.

TOF_VIS (no printing)

1. cd TOF_VIS/src
2. make all_noprint tof_vis

This should construct the executable "tof_vis" without printing. If that works OK try:

TOF_VIS ( with printing )

1. cd TOF_VIS/src
2. make all tof_vis
   

If a version of TOF_VIS that reads a simple clear text style data file is wanted:

TOF_VIS ( text file no printing )

1. cd TOF_VIS/src
2. make demo_noprint tof_vis_demo
   

TOF_VIS ( text file with printing )

1. cd TOF_VIS/src
2. make demo tof_vis_demo

If for some reason you are unable to use make to compile these routines on your system it should be possible to compile the libraries "by hand" and then compile and link the tof_vis executable "by hand".

NOTE: HP workstation use a different byte ordering ( big endian ) than the PC/Alpha/Vax/MIPS machines. To properly read the IPNS binary run files on an HP workstation, edit the IPNS_FileManager.c file in the directory <TOF>/FILE_READ/src to include the line

• #define IPNS_BIG_ENDIAN

before compiling.

D. VMS Installation

TOF_VIS has been compiled and tested on the following VMS platforms:

• DEC ALPHA running VMS 6.1
• DEC VAX running VMS 6.1

1. Unpack the TOF_VIS source tree creating the directory [TOF_2_0].
2. Define the following logicals as appropriate for your system:

   PGPLOT_INC ( directory containing the CPGPLOT.H file )
   
   PGPLOT_LIB ( directory containing the PGPLOT libraries )

   eg:

   $ define PGPLOT_INC ud4:[pgplot.cpg]
   
   $ define PGPLOT_LIB ud4:[pgplot_alpha]

3. Set default to [TOF_2_0.TOF_VIS.SRC]
4. Build tof_vis executables (@build_tof_vis.com). You will be asked whether to build for ASCII or IPNS data. Choose IPNS. The executable will be placed in [TOF_2_0.VAX_EXE] or [TOF_2_0.ALPHA_EXE] depending on the machine CPU.
5. Define the tvis command in your system or personal login file.
6. If you have a mixed VMS cluster, repeat steps 3-5 on the other type system (VAX or Alpha) using different directories for PGPLOT_LIB and the TOF_VIS executable.

The [TOF_2_0] directory will have four subdirectories: MATH_TOOLS,FILE_READ, MMOTIF_TOOLS, TOF_VIS. Each of these directories contains components of TOF_VIS, as described previously. Each of these directories contains a source ( [.src] ) subdirectory with the source code and a command file to compile the routines in that subdirectory. The build routine in the [TOF.TOF_VIS.SRC] directory will compile the routines in all the directories, then link TOF_VIS and place it in the appropriate directory (Different tof_vis_exe directories are defined for the VAX and Alpha executables. These directories are created when the build routine executes logicals.com.)

The version of TOF_VIS produced should be able to read the example IPNS data files provided in [TOF_2_0.SAMPLE_DATA].

E. Sample Data

The files TOF_2_0/SAMPLE_DATA/gppd6100.run and TOF_2_0/SAMPLE_DATA/hrcs1797.run contain data from the General Purpose Powder Diffractometer and High Resolution Chopper Spectrometer at IPNS. They can be loaded and viewed using TOF_VIS to test the functionality of TOF_VIS.

Since the data file format used at various facilities is not standardized (yet) we anticipate that it will be necessary for users of TOF_VIS to modify the data file access routines in TOF_VIS to read their own data files. A version of TOF_VIS that reads a very crude ASCII data file format may also be produced. This version is called tof_vis_demo in the Unix version. It may be built on VMS by choosing the ASCII file format option which will construct the executable "tof_vis" in a form that will read the demo data from "demo_data.txt"

The file demo_data.txt contains some very "low resolution", "phony" data that can be read and displayed using this version. It may however be useful if you wish to customize TOF_VIS to read other data file formats.

More information on customizing TOF_VIS is given below in the section on CUSTOMIZATION.

Back to Contents | Back to TOF_VIS Home Page