Introduction

The general structure of data that you will wind up with in your event file will be layered. This is largely a consequence of using the event builder, because the event builder wraps data from the Readout program with other data. In this section the structure of physics events will be broken down. It will be described in order of how it changes as it moves downstream from the Readout program.

Event Data Structure Produced by Readout

The section on the modevtlen.txt configuration file should have instilled a sense that the structure of outputted data from the Pixie-16 digitizers depends on the features enabled. We will describe the general structure of the outputted data and how it varies with each feature in this section.

First of all, it is important to recognize that the DDAS Readout program is just an implementation of the SBS Production Readout Framework. This has a couple implications. The first is that the DDAS Readout program outputs NSCLDAQ ring items. These ring items will always have body headers associated with them. The physics events will have bodies that begin with a 32-bit, inclusive count of the 16-bit words in the body. Following that word count, there is a 32-bit word containing the device information that is created by the Readout program. The raw data read out from the module follows the device information. A physics event therefore has the following complete structure:

DDAS Ring Item Structure (Physics event)

Top-level Feature	Description	Width (bytes)
Header	Size	4
Header	Type (=30)	4
Body Header	Size (=20)	4
	Timestamp	8
	Source id	4
	Barrier (=0)	4
Body	Inclusive size of body (# 16-bit words)	4
	Device information	4
	Raw data	...

The 32-bit word containing device information has the following format:

Bits	Description
0-15	ADC frequency (MSPS)
16-23	ADC resolution (bits)
24-31	Module revision

The raw data that is read from the device is at least four 32-bit words long. There is always a header that contains geographic information for the data, timestamp, energy, and trace length. If the user enables the QDC mode or energy summing mode, there will be either 4, 8, or 12 more 32-bit words in the header. Following the header, is the trace if the user chose to enable trace acquisition.

Let's break down the first four data words in the header. These are always the same.

Index	Description	Bit Meanings
0	Geographic information	[0:3]=channel, [4:7]=slot, [8:11]=crate, [12:16]=header length, [17:30]=event length, [31]=finish code
1	Timestamp bits 0-31	[0:31]=least significant 32-bits of timestamp
2	Timestamp bits 32-47, cfd	[0:15]=most significant 16-bits of timestamp, [16:31]=CFD time
3	Trace length and energy	[0:14]=energy, [15]=overflow/underflow, [16:31]=trace length

Remarks

The finish code pertains to pile up. If pile up occurred, this is set to 1.
The meaning of the CFD bits depend on the type of the Pixie-16 digitizer used. See the page on each module for details about the data it outputs.
The overflow/underflow bit is set whenever and overflow or underflow occurs in the ADC period of time whose length is equal to the length of the energy filter's rise and gap time. After that length of time passes, it is reset.

If the QDC mode or energy summing mode is enabled, then more data follows. If present, the energy summing mode data follows first followed by the QDC mode data. The energy summing mode data has the following form:

Index	Description	Bit meanings
0	Trailing energy sum	[0:31] Trailing energy sum
1	Leading energy sum	[0:31] Leading energy sum
2	Gate energy sum	[0:31] Gap energy sum
3	Baseline	[0:31] Baseline value

The QDC mode data has the following form:

Index	Description	Bit meanings
0	QDC sum 0	[0:31] QDC sum #0
1	QDC sum 1	[0:31] QDC sum #1
2	QDC sum 2	[0:31] QDC sum #2
3	QDC sum 3	[0:31] QDC sum #3
4	QDC sum 4	[0:31] QDC sum #4
5	QDC sum 5	[0:31] QDC sum #5
6	QDC sum 6	[0:31] QDC sum #6
7	QDC sum 7	[0:31] QDC sum #7

These data are followed by a trace if trace acquisition is enabled. There are two ADC samples in each 32-bit words, the least significant 16-bits corresponds to the sample that was digitized first. The number of valid bits is determined by the digitizer hardware.

So far, the data format that has been described is what you would see if you intercepted the data immediately out of the Readout program. If you follow the directions above, though, the data will proceed through the event builder as well. During this journey more data will be added to the event. The first transformation is that all ring items will be transformed into fragments. A fragment, like a ring item, has a header and a body, which we refer to as the payload. The raw ring item strucutre we described already will become the payload. A single fragment will therefore have the following structure:

DDAS Scaler Format

The Pixie-16 digitizers keep internal counters during a run that are read out periodically as scaler items. The readout period is 16 seconds, which is quite long. The reason for this is actually at the hardware/firmware level. Internally, some of the counters update only once every 16 seconds. Reading them out more often than 16 seconds will cause misleading information to be provided to the user because the values may not have updated yet. The rate would appear to be zero and yet it would not be in reality.

Every sixteen seconds, you should expect to get ring item of type PERIODIC_SCALERS in the data stream from each crate. This scaler data will have 33 "channels" of scaler data for each module in the crate. The reason for this is that each physical channel on the module has two scaler channels: input count and output count. Further, in between every module, the crate id is inserted. The format is therefore:

scaler channel	description
0	crate id
1	slot 2, ch.0 raw trigger count increment
2	slot 2, ch.0 validated trigger count increment
3	slot 2, ch.1 raw trigger count increment
4	slot 2, ch.1 validated trigger count increment
...	...
31	slot 2, ch.15 raw trigger count increment
32	slot 2, ch. 15 validated trigger count increment
33	crate id
34	slot 3, ch.0 raw trigger count increment
35	slot 3, ch.0 validated trigger count increment
36	slot 3, ch.1 raw trigger count increment
37	slot 3, ch.1 validate trigger count increment
...	...

Note: Because the value in the scalers are increments, you need to set up the ScalerDisplay to interpret the scaler data as "incremental".

DDAS Fragment Structure

Top-level Description	Description	Width (bytes)
Fragment header	Timestamp	8
	Source id	4
	Payload size (bytes)	4
	Barrier type (=0)	4
Payload	Ring item size	4
	Ring item type (=30)	4
	Timestamp	8
	Source id	4
	...	...

There is a one-to-one correspondence between physics events and fragments entering the event builder. The event builder then takes each of these fragments and assembles them into composite or built event. A built event is a standard ring item of type "physics event" that has a body composed of multiple fragments. There is also always a body header associated with it. The structure of the built ring item is therefore:

Built Ring Item Structure (Physics event)

Top-level Feature	Description	Width (bytes)
Header	Size	4
Header	Type (=30)	4
Body Header	Size (=20)	4
	Timestamp	8
	Source id	4
	Barrier (=0)	4
Body	Inclusive size of body (# 8-bit words)	4
	Fragment #0	...
	Fragment #1	...
	...	...

If the user turns off correlations in the event builder, then there will only ever be a single fragment per built event. Otherwise, there will be as many as correlate together within the the build window.