daq2lh5.compass package¶

This subpackage overloads decoding utilities defined in pygama.raw to read files produced by the CoMPASS software.

Submodules¶

daq2lh5.compass.compass_config_parser module¶

daq2lh5.compass.compass_config_parser.compass_config_to_struct(compass_config_file=None, wf_len=None)¶

Read run-level data from a CoMPASS configuration file.

Parameters:: compass_config_file (str | None) – an XML config file for a CoMPASS data run.
Returns:: config_struct – a struct of configuration data to pass to the streamer.
Return type:: Struct

JSON Configuration Example

{
    "boards" : {
        "0" : {
            "modelName" : "DT5730",
            "adcBitCount" : 14,
            "sample_rate" : 0.5,
            "wf_len" : 1000,
            "channels": {
                "0" : {
                    "Vpp": 2,
                }
            }
        }
    }
}

Notes

First, if the CoMPASS xml config is not none, it is turned into a dictionary. If the CoMPASS config file is none, then a generic struct with the maximum number of channels and boards is returned, in order to create the most generic raw buffer to fill.

daq2lh5.compass.compass_event_decoder module¶

class daq2lh5.compass.compass_event_decoder.CompassEventDecoder(header=None, *args, **kwargs)¶

Bases: DataDecoder

Decode CAEN digitizer event data.

decode_packet(packet, evt_rbkd, packet_id, header)¶

Access CoMPASSEvent members for each event in the DAQ file.

Parameters:

packet (bytes) – The packet to be decoded
evt_rbkd (Table | dict[int, Table]) – A single table for reading out all data, or a dictionary of tables keyed by channel number.
packet_id (int) – The index of the packet in the CoMPASS stream. Incremented by CompassStreamer.
header (Table | dict[int, Table]) – The header of the CoMPASS file, along with user config info, that is used to determine waveform lengths and thus buffer sizes

Returns:

n_bytes – (estimated) number of bytes in the packet that was just decoded.

Return type:

bool

get_decoded_values(key=None)¶

Get decoded values (optionally for a given key, typically a channel).

Notes

Must overload for your decoder if it has key-specific decoded values. Must also implement key = None returns a “default” decoded_values. Otherwise, just returns self.decoded_values, which should be defined in the constructor.

get_key_lists()¶

Return a list of lists of keys available for this decoder. Each list must contain keys that can share a buffer, i.e. decoded_values is exactly the same (including e.g. waveform length) for all keys in the list. Overload with lists of keys for this decoder, e.g. return [range(n_channels)]. The default version works for decoders with single / no keys.

Return type:: list[list[str]]

set_header(header)¶

daq2lh5.compass.compass_event_decoder.compass_decoded_values = {'board': {'dtype': 'uint32'}, 'channel': {'dtype': 'uint32'}, 'energy': {'dtype': 'uint32'}, 'energy_calibrated': {'dtype': 'float64'}, 'energy_short': {'dtype': 'uint32'}, 'flags': {'dtype': 'uint32'}, 'num_samples': {'dtype': 'int64'}, 'packet_id': {'dtype': 'uint32'}, 'timestamp': {'dtype': 'float64', 'units': 'ps'}, 'waveform': {'datatype': 'waveform', 'dt': 16, 'dt_units': 'ns', 'dtype': 'uint16', 't0_units': 'ns', 'wf_len': 65532}}¶: Default CoMPASS Event decoded values.

Warning

This configuration can be dynamically modified by the decoder at runtime.

daq2lh5.compass.compass_event_decoder.get_bc(board, channel)¶

Create a standard hash for the board and channel of a CoMPASS file.

Return type:: int

daq2lh5.compass.compass_header_decoder module¶

class daq2lh5.compass.compass_header_decoder.CompassHeaderDecoder(*args, **kwargs)¶

Bases: DataDecoder

Decode CoMPASS header data. Also, read in CoMPASS config data if provided using the compass_config_parser

decode_header(in_stream, config_file=None)¶

Decode the CoMPASS file header, and add CoMPASS config data to the header, if present.

Parameters:

in_stream (bytes) – The stream of data to have its header decoded
config_file (str | None) – The config file for the CoMPASS data, if present

Returns:

config – A dict containing the header information, as well as the important config information of wf_len and num_enabled_channels

Return type:

dict

make_lgdo(key=None, size=None)¶

Make an LGDO for this DataDecoder to fill.

This default version of this function allocates a Table using the decoded_values for key. If a different type of LGDO object is required for this decoder, overload this function.

Parameters:

key (int | None) – used to initialize the LGDO for a particular key (e.g. to have different trace lengths for different channels of a piece of hardware). Leave as None if such specialization is not necessary.
size (int | None) – the size to be allocated for the LGDO, if applicable.

Returns:

data_obj – the newly allocated LGDO.

Return type:

Struct

daq2lh5.compass.compass_streamer module¶

class daq2lh5.compass.compass_streamer.CompassStreamer(compass_config_file=None)¶

Bases: DataStreamer

Data streamer for CoMPASS data streams.

_abc_impl = <_abc._abc_data object>¶

close_stream()¶

Close this data stream.

get_decoder_list()¶

Returns a list of decoder objects for this data stream.

Notes

Needs to be overloaded. Gets called during open_stream().

Return type:: list[DataDecoder]

load_packet()¶

Loads the next packet into the internal buffer.

Returns packet as a numpy.uint32 view of the buffer (a slice), returns None at EOF.

Notes

First, load_packet finds the packet’s metadata length in bytes by looking at the header, and then reads the metadata into the buffer. From the metadata, the length of the waveform can be determined and then the buffer is resized to fit the metadata and the waveform. Finally, the buffer is filled with the packet and then returned.

Return type:: uint32 | None

open_stream(stream_name, rb_lib=None, buffer_size=8192, chunk_mode='any_full', out_stream='')¶

Initialize the CoMPASS data stream. If a config file is present, load just the 2 byte header. If a config file is absent, read the first packet to determine waveform length, and initialize the keys to the max number of channels of a CAEN digitizer.

Parameters:

stream_name (str) – The CoMPASS filename. Only file streams are currently supported. Socket stream reading can be added later.
rb_lib (RawBufferLibrary | None) – library of buffers for this stream.
buffer_size (int) – length of tables to be read out in read_chunk().
chunk_mode ('any_full', 'only_full', or 'single_packet') – sets the mode use for read_chunk().
out_stream (str) – optional name of output stream for default rb_lib generation.

Returns:

header_data – a list of length 1 containing the raw buffer holding the CoMPASS header.

Return type:

tuple[list[RawBuffer], int]

Notes

CoMPASS files have a header that is only 2 bytes long and only appears at the top of the file. So, we must read this header once, and then proceed to read packets in.

read_packet()¶

Read and decode a packet of data. Data written to the event_rbkd attribute.

Return type:: bool

set_in_stream(stream_name)¶

Sets the in_stream by opening a binary file