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
Topic revision: r8 - 2008-10-02, MichaelBoehmer
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki Send feedback | Imprint | Privacy Policy (in German)