triumf_format.txt

TRIUMF_FORMAT.TXT D. Maden. 11-Feb-1992 ================= 0. Modification History -------------------- ??? Initial version. No format ID. ??-Mar-1991 DM ID = '1A'. Spike data introduced. 11-Feb-1992 DM ID = '1B'. Bug fix in spike data. On earlier files, to get the correct bin numbers for the spikes subtract n*LENGTH from the bin numbers where n is chosen so that the result is in the range 0 to LENGTH-1 (LENGTH is the number of bins in the histogram). 1. Introduction ------------ This note describes the "TRIUMF" data format written by the MODAS TD_muSR data acquisition system. The final part of this note is the Fortran include file used in the data archiving program, DARC, to define the file and histogram header records. The include file is SG0:[MADEN.TD_MUSR.SOURCES.DARC]TRIUMF_FMT.FINC on PSICLU. The critical parameters in the OPEN statement which creates a TRIUMF data file are: form = 'unformatted' recordtype = 'fixed' recl = 128 giving files with fixed length, unformatted records of 512 bytes each. To read a TRIUMF format data file in a Fortran program, the only critical parameter to be specified in the 'Open' statement is: form = 'unformatted' Read commands should read data into a 512 byte buffer. 2. Notes on the Various Items -------------------------- 2.1 File Header: ----------- MRUN negative values of this field are used in I_muSR data files to indicate that the file is an I_muSR file rather than a TD_muSR file. Run numbers are therefore in the range 0 to 32767. MSUPD is set to the time between updates of the disk data file (usually 300 secs). JTSC(18) are the scaler contents in "inverted Integer*4" form. i.e. the least significant 16 bits of a 32 bit item contain the most significant 16 bits of the scaler value and vice versa. This is done for compatibility with the PDP-11 data acquisition system. JDSC(18) are always zero. The singles scalers are not read and cleared every few seconds as they used to be in the PDP-11 system. MMIN, MSEC are simply computed from (MTEND-MTNEW). No allowance is made at present for time during which data acquisition is paused. MLSTON(4) are simply a copy of MTNEW(3) to MTNEW(6). MCMCSC is currently 1 since MODAS only supports a single multiscaler. There are plans to increase this number. MLOCSC(1,I) are the station number of the scalers. MLOCSC(2,I) are always 6 - the scalers are assumed to have 6 sub-addresses. MRSTA, ACQTSK, MUIC are always zero. NEVTOT is the sum of the NEVTOT entries in each histogram header (see below). It is in "inverted Integer*4" form like JTSC. MHSTS, MBINS, MSHFT are always zero. Noone could tell me what these were supposed to be. TITLE(40) is set to the first 40 chars of the run title. SCLBL(72) contain the scaler labels, truncated to 4 characters. COMENT(144) contain the full run title in the first 80 characters followed by 4 fields each of 10 characters containing the sample/temperature/field/orientation information respectively. The next 10 chars contain the Rig name and the next 10 chars the preset data acquisition mode. 2.2 Histogram Header: ---------------- Note: Histogram Headers always start at the beginning of a disk record. IHIST is the number of the histogram in the file, i.e. an integer from 1 to MHISTS. LENGTH is the number of bins in the histogram. In practice, all histograms will have the same length which will be a multiple of 256. NEVTOT is the sum of all the bins in the histogram in "inverted Integer*4" format (see JTSC). Note: this sum is done on the 24 bit quantities read from the histogram memory BEFORE they are truncated to 16 bits for writing to disk. NTPBIN is the resolution code of the Lecroy 4204 TDC module. These are 0 = 78 psec 4 = 1.25 nsec 8 = 20 nsec 12 = 320 nsec 1 = 156 psec 5 = 2.5 nsec 9 = 40 nsec 13 = 640 nsec 2 = 312 psec 6 = 5 nsec 10 = 80 nsec 14 = 1280 nsec 3 = 625 psec 7 = 10 nsec 11 = 160 nsec 15 = 2560 nsec MASK is the input of the NIM/ECL converter used to direct signals from the muon counter to the TDC. This gives the location in the histogram memory where the histogram data is stored. A value of 1 means that the data will start at location zero in the HM. ID If set to "1A" or greater, indicates that there is spike data stored in the spare space after the last histogram bin. Histogram Data is stored as unsigned 16 bit items directly following the histogram header. Any bins which overflow 16 bits cause an entry in the "spike data buffer" if ID >= "1A". 2.3 Spike Data: ---------- Since LENGTH is forced to a multiple of 256, there are always 448 bytes of free space in the last disk record of a histogram. From March 1991, this space is used to store information on bins in the histogram which overflowed 16 bits. The format of this spike data is +----------------------------------+ | Number of bins in spike, NB | <-- always an even number +----------------------------------+ | Bin number of start of spike, B0 | +---------------+------------------+ \ | Byte 0 | Byte 1 | \ NB overflow bytes for +---------------+------------------+ > each bin in spike. | Byte 2 | etc. | / +---------------+------------------+ / If NB = 2, B0 = -1 and Byte 0 and Byte 1 are both 255 then this indicates that the spike data has overflowed the space available. A spike with NB = 0 indicates the end of the spike data. 3. The Fortran Include File ------------------------ This is on the next page.  c---------------------------------------------------- TRIUMF_FMT.FINC Ident 1A04 c Run Parameters Block (512 bytes) c structure /tmf_f_hdr/ ! TRIUMF File Header integer*2 mrun ! Run Number. integer*2 mhists ! Number of Histograms to follow. integer*2 msclr ! Number of Scalers recorded (max. 18). integer*2 msupd ! # of Seconds between Scaler Updates. integer*4 jtsc(18) ! Scaler Totals. integer*4 jdsc(18) ! Latest Scaler Contents. integer*2 mmin ! Number of elapsed Minutes in this Run. integer*2 msec ! # of additional elapsed Seconds. integer*2 mtnew(6) ! NEWRUN date & time (Y,M,D,H,M,S). integer*2 mtend(6) ! ENDRUN date & time (Y,M,D,H,M,S). integer*2 mlston(4) ! Time of latest 'ACQ ON' (D,H,M,S). integer*2 mcmcsc ! Number of CAMAC Multiscalers (max. 6). integer*2 mlocsc(2,6) ! Crate Addresses (N) and .. ! .. Multiplicities (max A + 1) of CAMAC Scalers integer*2 mrsta ! Current Run Status Code (RAD50). integer*4 acqtsk ! Name of Data Acquisition Task. logical*1 logfil(10) ! Name of Log File (ED:[DLOG] assumed). integer*2 muic ! UIC under which one runs data acq. integer*4 nevtot ! Total Events in all Histograms. integer*2 mhsts ! Same as MHISTS; word 1 in 3-word .. ! .. SIN control block. integer*2 mbins ! # of spectra; word 2 ... integer*2 mshft ! # of times to shift raw ADC word; word 3 ... integer*2 mspare(7) ! unused words for now. logical*1 title(40) ! 40-character Run Title. logical*1 sclbl(72) ! 18 4-character Scaler Labels. logical*1 coment(144) ! 144-character Comment buffer. end structure ! End of TMF_F_HDR c structure /tmf_h_recd/ ! TRIUMF histogram record union map integer*2 ihist ! Histogram number integer*2 length ! Length of histogram (words) integer*4 nevtot ! Total of events integer*2 ntpbin ! Picosecs per bin (TDC code, 1 - 15) integer*4 mask ! Event masks (= input to NIM/ECL converter) integer*2 nt0 ! 'Origin' bin integer*2 nt1 ! 'Start of Good' bin integer*2 nt2 ! 'End of Good' bin logical*1 htitl(10) ! Histogram title logical*1 id(2) ! Ident to indicate spike data present logical*1 fill(32) integer*2 head_bin ! First bin in header recd goes here. end map map integer*2 data(256) end map end union end structure ! tmf_h_hdr c-------------------------------------------------------- End of TRIUMF_FMT.FINC