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.Münch, modified the headers
  • v1.0 by B.Kolb and M.Münch, minor changes after discussion with H.Essel...
  • v1.1 by M. Münch, changes in headers resulting from ht97 beam time
  • v1.2 by M. Münch, changes terminology and clarification of some points resulting from 1998-02-10 DAQ-Meeting
  • v1.3 by M. Münch, mainly defining some magic numbers and error bit in subevtid
  • v1.4 by M. Münch, define the experiment id, define the error bit in evtid, allow for variable set of sub events in one event
  • v1.5 by M. Münch, remove the experiment id, the evtFileNr is not connected to the date any more, minor changes and updates.
  • v1.6 by M. Münch, 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

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 sub divisions

Event

Events consist out of a fixed size event header and a varying number of variable size subevents.

Event header:

evtHeader
evtSize evtDecoding evtId evtSeqNr evtDate evtTime runNr expId

  • evtSize - size of the event: This includes 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
  1. The first (most significant) byte is always zero.
  2. The second byte contains the alignment of the subevents in the event. 0 = byte, 1 = 16 bit word, 2 = 32 bit word...
  3. 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..
  • 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:
    evtDate
    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]

(this is the date format of ISO-C)
  • evtTime - time of assembly:
    evtTime
    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]

(this is the time format of ISO-C)

The date and time field are filled in by the event builder and have thus only rough precision.
  • evtFileNr - file number: A unique number assigned to the file. The evtFileNr can be used as key to the run database.
  • evtPad - padding: Makes the event header a multiple of 64 bits long.

  • The subevents: Every event contains zero to unspecified many subevents. An empty event is allowed, data outside any subevent is not allowed.

Subevent

Subevents consist out of a fixed size subevent header and a varying number of data words.

  • The sub event header:
    subEvtHeader
    subEvtSize subEvtDecoding subEvtId subEvtTrigNr
  1. subEvtSize - size of the subevent: This includes the the subevent header, it is measured in bytes.
  2. 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
    1. The first (most significant) byte is always zero
    2. The second byte contains the word length of the subevent data. 0 = byte, 1 = 16 bit word, 2 = 32 bit word...
    3. 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.
  • 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 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.

Assigned Numbers

Event Id

The following ranges of evtIds are assigned to the several types:

1-999 Physics: bit[3..0] mirror the LVL2 trigger code from the trigger bus, bit[7..4] mirror the MU trigger info
1500-1999 Slow/Run Control
2000-2999 Simulation
4096-8191 Physics: bit[3..0] mirror the LVL1 trigger code from the trigger bus, bit[7..4] mirror the MU trigger info

For events that resulted from a trigger on the trigger bus, all bits are zero and the least significant bits mirror the trigger code that was indicated by the trigger system.

Additionally, all evtIds may have the MSB set. This indicates an event of the corresponding id that contains broken data (e.g. trigger tag mismatch). Sub Event Id

The following ranges of subEvtIds are assigned to the several groups:

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

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.).

LVL1 trigger code

0x1 (NORM1) physics trigger 1, lowest priority
0x2 (NORM2) physics trigger 2
0x3 (NORM3) physics trigger 3
0x4 (NORM4) physics trigger 4
0x5 (NORM5) Physics Trigger 5
0x6 (SPEC1) not defined yet
0x7 (SPEC2) 0.1Hz offspill
0x8 (SPEC3) not defined yet
0x9 (SPEC4) 10Hz, MDC-calibration
0xa (SPEC5) not defined yet, highest priority

MU trigger info

bit[4] downscaled event flag: if set, event was downscaled
bit[7..5] MU trigger algo result

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

-- MichaelTraxler - 10 Jan 2006
Edit | Attach | Print version | History: r8 | r5 < r4 < r3 < r2 | Backlinks | View wiki text | Edit WikiText | More topic actions...
Topic revision: r4 - 17 Jul 2008, MartinJurkovic
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Hades Wiki? Send feedback
Imprint (in German)
Privacy Policy (in German)