HADES raw data format

document is signed up to version 1.3

Purpose

This document describes the raw data format of the HADES data acquisition system. All Readout Controllers (RC) and the Event Builder (EB) have to follow the standard described in this document and format the data accordingly revision history

• v0.9 by B.Kolb, derived from WA98 data format
• v0.95 by M.Mnch, modified the headers
• v1.0 by B.Kolb and M.Mnch, minor changes after discussion with H.Essel...
• v1.1 by M. Mnch, changes in headers resulting from ht97 beam time
• v1.2 by M. Mnch, changes terminology and clarification of some points resulting from 1998-02-10 DAQ-Meeting
• v1.3 by M. Mnch, mainly defining some magic numbers and error bit in subevtid
• v1.4 by M. Mnch, define the experiment id, define the error bit in evtid, allow for variable set of sub events in one event
• v1.5 by M. Mnch, remove the experiment id, the evtFileNr is not connected to the date any more, minor changes and updates.
• v1.6 by M. Mnch, change in structure, added the appendix for assigned numbers following a discussion about the versioning of the event id
• v1.7 by M. Traxler, added new subevent ids for TRB-kind-subevents
• v1.8 by J.Wuestenfeld, corrected Subevent Id tables to match
• v1.9 by M. Jurkovich, cleanup and adding some information

project status: current

Logical structure

• The data is contained in files. The term file in this document corresponds to one data file that is created directly by the data acquisition or simulation. Files that are created during the analysis procedure (e.g. by concatenating or filtering) are not covered here.
• Files consist out of events.
• Events consist out of an event header and sub events. The set of sub events may be empty.
• Sub events consist out of the sub event header and the sub event data. The sub event data may be empty.

No record scheme or application level buffering is used above the event level.

Physical structure

• On tape, files will be written using the ANSI labeling scheme. On disk, the file system structure is operating system dependent.
• On tape, files are written in fixed size blocks of 8192 bytes (8 KBytes). On disk, files will be written as a byte stream file.
• A file should be kept in a reasonable size for the computing environment (2GB).
• The file name of the original data file represents the date when the file was opened in the format: xxyydddhhmmss.hld (xx: experiment id, yy: year, ddd: day of year, hh: hour, mm: minute, ss: second)
• All header words are 32bit words.
• If several divisions (like several subevents) are stored or transported together (like in an event) then all divisions (events, subevents, headers, data bodies...) start on a 64bit boundary, unless it is defined explicitly otherwise. This implies, that headers are an even number of 32bit words long. Length words of headers count only the used part of data. The location of the next division is assumed to be rounded up to the next 64bit boundary.
• The byte ordering of words is that of the machine that produced the data, the reading software must take care of swapping (receiver makes it right).
• If byte swapping is necessary, it must be done in four byte units (32bit words), unless it is defined explicitly otherwise. * All divisions start with a word describing the size of the whole division in bytes. This includes the size word itself.

Description of the Event Structure

An event consists of an event header and of varying number of subevents, each with a subevent header. The size of the event header is fixed to 0x20 bytes

Event header

evtHeader
evtSize	evtDecoding	evtId	evtSeqNr	evtDate	evtTime	runNr	expId

• evtSize - total size of the event including the event header, it is measured in bytes.
• evtDecoding - event decoding type: Tells the analysis the binary format of the event data, so that it can be handed to a corresponding routine for unpacking into a software usable data structure. For easier decoding of this word, the meaning of some bits is already predefined:

  evtDecoding
  msB	---	---	lsB
  0	alignment	decoding type	nonzero

  • The first (most significant) byte is always zero.
  • The second byte contains the alignment of the subevents in the event. 0 = byte, 1 = 16 bit word, 2 = 32 bit word...
  • The remaining two bytes form the actual decoding type, e.g. fixed length, zero suppressed etc.
  • The last byte must not be zero, so the whole evtDecoding can be used to check for correct or swapped byte order.

It is stated again, that the whole evtDecoding is one 32bit word. The above bit assignments are merely a rule how to select this 32bit numbers.

• evtId - event identifier: Tells the analysis the semantics of the event data, e.g. if this is a run start event, data event, simulated event, slow control data, end file event, etc..

  evtId
  31	30 - 16	15 - 12	11 - 8	5 - 7	4	3- 0
  error bit	reserved	version	reserved	MU decision	DS flag	ID

  • error bit - set if one of the subsystems has set the error bit
  • version - 0 meaning of event ID before SEP03; 1 event ID after SEP03
  • MU decision - 0 = negative LVL2 decision; >0 positive LVL2 decision

    MU trigger algo result
    1	negative decision
    2	positive decision
    3	positive decision due to too many leptons or dileptons
    4	reserved
    5	reserved

  • DS flag - LVL1 downscaling flag; 1 = this event is written to the tape independent on the LVL2 trigger decision
  • ID - defines the trigger code

    ID before SEP03	description
    0	simulation
    1	real
    2,3,4,5,6,7,8,9	calibration
    13	beginrun
    14	endrun

    
    

    ID after SEP03	description
    0	simulation
    1,2,3,4,5	real
    7,9	calibration
    1	real1
    2	real2
    3	real3
    4	real4
    5	real5
    6	special1
    7	offspill
    8	special3
    9	MDCcalibration
    10	special5
    13	beginrun
    14	endrun

• evtSeqNr - event number: This is the sequence number of the event in the file. The pair evtFileNr/evtSeqNr

is unique throughout all events ever acquired by the system.

• evtDate - date of event assembly (filled by the event builder, rough precision):

  evtDate	ISO-C date format
  msB	---	---	lsB
  0	year	month	day

1. The first (most significant) byte is zero
2. The second byte contains the years since 1900
3. The third the months since January [0-11]
4. The last the day of the month [1-31]

• evtTime - time of assembly (filled by the event builder, rough precision):

  evtTime	ISO-C time format
  msB	---	---	lsB
  0	hour	minute	second

1. The first (most significant) byte is zero
2. The second byte contains the hours since midnight [0-23]
3. The third the minutes after the hour [0-59]
4. The last the seconds after the minute [0-60]

• runNr - file number: A unique number assigned to the file. The runNr is used as key for the RTDB.
• evtPad - padding: Makes the event header a multiple of 64 bits long.

Subevent

Every event contains zero to unspecified many subevents. As an empty event is allowed, data outside of any subevent are not allowed. A subevents consists out of a fixed size subevent header and a varying number of data words.

• The subevent header

  subEvtHeader
  subEvtSize	subEvtDecoding	subEvtId	subEvtTrigNr

  • subEvtSize - size of the subevent: This includes the the subevent header, it is measured in bytes.
  • subEvtDecoding - subevent decoding type: Tells the analysis the binary format of the subevent data, so that it can be handed to a corresponding routine for unpacking into a software usable data structure. For easier decoding of this word, the meaning of some bits is already predefined:

    subEvtDecoding
    msB	---	---	lsB
    0	data type	decoding type	nonzero

    • The first (most significant) byte is always zero
    • The second byte contains the word length of the subevent data. 0 = byte, 1 = 16 bit word, 2 = 32 bit word...
    • The remaining two bytes form the actual decoding type, e.g. fixed length, zero suppressed etc.
    • The last byte must not be zero, so the whole subEvtDecoding can be used to check for correct or swapped byte order. It is stated again, that the whole subEvtDecoding is one 32bit word. The above bit assignments are merely a rule how to select this 32bit numbers.
  • subEvtId - subevent identifier: Tells the analysis the semantics of the subevent data, e.g. every subevent builder may get its own subEvtId. So the data structure can be analyzed by the corresponding routine after unpacking.

    1-99	DAQ
    100-199	RICH
    200-299	MDC
    300-399	SHOWER
    400-499	TOF
    500-599	TRIG
    600-699	SLOW
    700-799	TRB_RPC	common TRB, but contents is RPC
    800-899	TRB_HOD	pion-hodoscope
    900-999	TRB_FW	forward wall
    1000-1099	TRB_START	start detector
    1100-1199	TRB_TOF	TOF detector
    1200-1299	TRB RICH	RICH detector

Additionally, all subEvtIds may have the MSB set. This indicates a sub event of the corresponding id that contains broken data (e.g. parity check failed, sub event was too long etc.).

• • subEvtTrigNr - subevent Trigger Number: This is the event tag that is produced by the trigger system and is used for checking the correct assembly of several sub entities. In general, this number is not counting sequentially. The lowest significant byte represents the trigger tag generated by the CTU and has to be same for all detector subsystems in one event. The rest is filled by the EB.
• The data words: The format of the data words (word length, compression algorithm, sub-sub-event format) is defined by the subEvtDecoding and apart from this it is completely free. The meaning of the data words (detector, geographical position, error information) is defined by the subEvtId and apart from this it is completely unknown to the data acquisition system.

-- MichaelTraxler - 10 Jan 2006