RadWare97 introduces two new replay / tape scanning programs, namely 4play (for compressed 4-dimensional hypercubes) and incub8r3 (for compressed 3-dimensional cubes). These programs are similar to the old incub8r; for example, they allow for non-linear gains through the use of look-up tables, etc. However, they use a custom-designed compression algorithm to reduce the size of the files required to hold these huge histograms.
4play will create a hypercube that is fully symmetrized; that is, it is a 1/24 cube, with w <= x <= y <= z. The hypercube can be gated/inspected by the new programs 4dg8r, or its MOTIF version xm4dg. The hypercube may be, and generally should be, split over a number of disk files. This is in order to allow the cube to be spread over different partitions, disks, or even computer systems.
In addition to 4play and 4dg8r, three other programs were written, namely make4cub, split4cub and pro4d. Make4cub is used to create a new (empty) hypercube. Should you later discover that one or more of the subfiles that comprise this cube are getting too large, you may further subdivide them using split4cub. Pro4d will read through a hypercube and create the three-dimensional projection, as a .cub file. This .cub file can then in turn be projected down to 2D and 1D by using pro3d.
The current default limits on the size of RadWare hypercube files is 1024 channels per side, or about 40 Gchs for a 1/24 cube. You can change this limit by editing the files 4play.h, pro4d.h and levit8r.h in the RadWare source directory, and modifying the value of RW_MAXCH or MAXCHS. In 4play.h, you will also have to change the values of RW_LB1, RW_LB2 and RW_DB2.
Since the hypercube is compressed, the total size of the histogram depends not only on the number of channels, but also on the number of counts. As more counts are added to the cube, it will grow in size, at first by about one byte per count, and then more and more slowly. At high count densities (greater than average densities of about 0.3 counts/channel), it will grow by about one bit per channel for an additional factor of two in the total number of counts. To give you a feeling for the disk space required, my first hypercube was 856 channels per side, and had a total size of 4 GB when it contained 9Gigacounts. You will also require of the order of 1 or 2 GB of scratch disk space.
HOW TO USE 4PLAY.
In order to map the ADC channel data on your tape to the cube channels,
4play will need a look-up table in the RadWare .tab format. You can easily
create such a file with the program lufwhm. You will need to have some
idea of the range of ADC channels that you wish to incude in your cube.
If you wish to use nonlinear gains, you should also have some idea of how
the width (FWHM) of the peaks varies with energy; you will need to specify
this in terms of parameters like those used to define the starting width
in gf3, see gf3.hlp or the escl8r/levit8r NIM paper for details.
If you do not want to use nonlinear gains, you can simply enter
1, 0, 0
as the FWHM parameters, to pretend that you have a constant FWHM of 1 channel.
Lufwhm, when it creates your .tab file, tells you the number of channels per side required for the hypercube. You should make a note of this number, and then create a new, empty hypercube of this size by running the program make4cub.
Before using 4play with your data tapes, you may need to rewrite or modify the file get_event.c. This is a routine to extract event data from the tape buffers. Examples of get_event.c are included in the RadWare source directory for a few common event tape formats, as well as versions that produce random-number-generated energies and a superdeformed-band-like grid. Reproduced below is a header comment from these examples that describes the requirements of a get_event.c source code file.
/**************************************************************************** * get_event routine for 4play or incub8r3 * * get_event is called by the main program on an event-by-event basis * * to extract the Ge energies from the global tape data buffer * * char *tbuf of size gd.RecordSize. * * The Ge energies are returned in the array * * int *elist of size RW_MAXMULT. * * The returned value from get_event is the number of Ge energies, * * i.e. the Ge multiplicity, * * or -1 if the end of the data buffer is reached. * * Thus if get_event returns the value -1, the main program * * will read the next tape buffer before calling get_event again. * ***************************************************************************/Please note that get_event.c is the only source code that you should need to modify.
Once you have created your ADC-to-cube-channel lookup .tab file and
your new hypercube, and have found or written an appropriate get_event.c
file, you should compile the program, using for example the command
make 4play
from within the RadWare source directory. You are then almost ready
to begin sorting.
In order to simplify the input of filenames and tape device names etc to 4play, the program asks for and reads a data file with the default filename 4play.inc. An example 4play.inc is included in the RadWare source directory and reproduced below:
============= example 4play.inc =============
Er154,155 4d tests Eurogam presorted tapes
/dev/rmt0h
er.scr
er.4d
er.tab
16384
1500
n
--------------------------------------------------
The above lines provide the following information to 4play:
line 1: user-provided title for the replay task
line 2: name for the input tape drive device to be used
line 3: name to be used for the "scratch" disk file
line 4: name of the 4D hypercube directory file
line 5: name of the look-up table file to be used to map ADC chs to cube chs
(generally produced by running the program lufwhm)
line 6: block size for the records to be read from tape, in bytes
line 7: size to be used for the "scratch" disk file, in MB
(should generally be at least several hundred MB
in order to minimize scanning time)
line 8: y(es) or n(o) to specify whether the records read from tape need
to be byte-swapped
NOTE: If the 4D hypercube directory file does not yet exist (i.e. you
are starting a new replay) you will need to create it by running
the program make4cub. Recommended filename extensions are .4d
for the directory file and .4cub for the actual hypercube files.
============= end of example 4play.inc =============
So you need to edit the example .inc file provided, to match the device
and file names and sizes that you wish to use, etc. You will then be ready
to run 4play.
When you run 4play, you simply need to follow directions and answer questions. The existing hypercube file(s) will be checked to make sure that the number of channels matches the .tab file etc. The scratch file is used to store a large number of increments, so that the hypercube does not have to be read, decompressed, incremented, recompressed and rewritten very often. After you have finished your replay, and successfully exited from 4play, you may safely delete the scratch file without losing any information.
As each tape is scanned by 4play, you are given options to change tape drives, skip over data records, replay only a certain number of files or records, etc. The default action, however, obtained by pressing return to each of the questions, is to replay the whole of each tape. If at any time you wish to interrupt the replay in the middle of a tape, press control-C; the flow of the program will be interrupted before the next buffer is read from tape, and you will be given the option of exiting gracefully from the program or continuing with the replay.
If, during the scan, you wish to check the one-dimensional spectrum of the Ge energies (in ADC channels, i.e. before being transformed to the cube channels), use control-C to interrupt the scan and then look at the file 4play.spn with gf3. Row 0 (sp 0) will contain the first 4096 channels of the ADC spectrum. In addition, Row 2 (sp 2) will contain a spectrum of the Ge multiplicity.
Whenever the scratch file becomes full, the hypercube is read and incremented; this is also done as you exit from the program.
PLEASE send reports of problems and/or bugs to radforddc@ornl.gov