daq2lh5.orca package¶

This subpackage overloads decoding utilities defined in pygama.raw to read files produced by the ORCA acquisition system.

Submodules¶

daq2lh5.orca.orca_base module¶

class daq2lh5.orca.orca_base.OrcaDecoder(header=None, **kwargs)¶

Bases: DataDecoder

Base class for ORCA decoders.

Mostly here to provide a standard interface for setting the header during initialization.

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

daq2lh5.orca.orca_base.get_card(ccc)¶

Get card number back from hash value.

daq2lh5.orca.orca_digitizers module¶

class daq2lh5.orca.orca_digitizers.ORSIS3302DecoderForEnergy(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for Struck SIS3302 digitizer data written by ORCA.

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

decoded_values_template¶: Default Struck SIS3302 (read out by ORCA) waveform decoded values.

Warning

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

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.

Return type:: dict[str, Any]

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[int]]

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

class daq2lh5.orca.orca_digitizers.ORSIS3316WaveformDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for Struck SIS3316 digitizer data written by ORCA.

decode_packet(packet, packet_id, rbl)¶

Decode the ORCA SIS3316 ADC packet.

The packet is formatted as:

xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
^^^^ ^^^^ ^^^^ ^^----------------------- Data ID (from header)
-----------------^^ ^^^^ ^^^^ ^^^^ ^^^^- length
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
--------^-^^^--------------------------- Crate number
-------------^-^^^^--------------------- Card number
--------------------^^^^ ^^^^----------- Chan number
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Num Events in this packet
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Num longs in each record
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Num of Records that were in the FIFO
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Num of longs in data header -- can get from the raw data also
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Spare
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Spare
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Spare
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Spare

Then, data events follow with format described in below (note the format bits):

xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
-----------------------------------^^^^- Format bits (from header)
--------------------^^^^ ^^^^ ^^^^------ Channel ID
^^^^ ^^^^ ^^^^ ^^^^--------------------- Timestamp[47:32]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx  Timestamp[31:0]
if Format bit 0 = 1 add
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
--------------------^^^^ ^^^^ ^^^^ ^^^^- Peakhigh value
^^^^ ^^^^ ^^^^ ^^^^--------------------- Index of Peakhigh value
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
----------^^^^ ^^^^ ^^^^ ^^^^ ^^^^ ^^^^- Accumulator sum of Gate 1 [23:0]
^^^^ ^^^^------------------------------- Information byte
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 2 [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 3 [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 4 [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 5 [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 6 [27:0]
If Format bit 1 = 1 add
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 7 [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Accumulator sum of Gate 8 [27:0]
If Format bit 2 = 1 add
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx MAW Maximum value [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx MAW Value before Trigger [27:0]
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx MAW Value after/with Trigger [27:0]
If Format bit 3 = 1 add
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Start Energy Value (in Trigger Gate)
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx Max Energy Value (in Trigger Gate)
Regardless of format bit
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
-------^^ ^^^^ ^^^^ ^^^^ ^^^^ ^^^^ ^^^^- number of raw samples divided by 2
------^--------------------------------- status Flag
-----^---------------------------------- MAW Test Flag
Followed by N ADC Raw Samples (2 Samples per 32 bit word)
Followed by MAW Test data

Return type:: bool

decoded_values_template¶: Default Struck SIS3316 (read out by ORCA) waveform decoded values.

Warning

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

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[str]]

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

daq2lh5.orca.orca_fcio module¶

class daq2lh5.orca.orca_fcio.ORFCIOConfigDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[str]]

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

class daq2lh5.orca.orca_fcio.ORFCIOEventDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for FlashCam FCIO stream data written by ORCA.

decode_packet(packet, packet_id, rbl)¶

Decode the ORCA FlashCam ADC packet.

Return type:: bool

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[int | str]]

get_max_rows_in_packet()¶

Returns the maximum number of rows that could be read out in a packet.

1 by default, overload as necessary to avoid writing past the ends of buffers.

Return type:: int

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

class daq2lh5.orca.orca_fcio.ORFCIOEventHeaderDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[str]]

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

class daq2lh5.orca.orca_fcio.ORFCIOStatusDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[str]]

get_max_rows_in_packet()¶

Returns the maximum number of rows that could be read out in a packet.

1 by default, overload as necessary to avoid writing past the ends of buffers.

Return type:: int

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

daq2lh5.orca.orca_fcio.extract_header_information(header)¶

daq2lh5.orca.orca_fcio.get_fcio_stream(streamid)¶

daq2lh5.orca.orca_flashcam module¶

class daq2lh5.orca.orca_flashcam.ORFlashCamADCWaveformDecoder(header=None, **kwargs)¶

Bases: ORFlashCamWaveformDecoder

class daq2lh5.orca.orca_flashcam.ORFlashCamListenerConfigDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for FlashCam listener config written by ORCA.

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

decoded_values¶: Default FlashCam (read out by ORCA) config decoded values.

Warning

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

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

class daq2lh5.orca.orca_flashcam.ORFlashCamListenerStatusDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for FlashCam status packets written by ORCA

Some of the card level status data contains an array of values (temperatures for instance) for each card. Since lh5 currently only supports a 1d vector of 1d vectors, this (card,value) data has to be flattened before populating the lh5 table.

decode_packet(packet, packet_id, rbl)¶

Return type:: bool

decoded_values¶: Default FlashCam (read out by ORCA) status decoded values.

Warning

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

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

class daq2lh5.orca.orca_flashcam.ORFlashCamWaveformDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for FlashCam ADC data written by ORCA.

assert_nsamples(nsamples, fcid)¶

decode_packet(packet, packet_id, rbl)¶

Decode the ORCA FlashCam ADC packet.

Return type:: bool

decoded_values_template¶: A custom copy of fc.fc_event_decoder.fc_event_decoded_values.

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

get_key_lists()¶

Return type:: list[list[int]]

set_header(header)¶

Setter for headers. Overload to set card parameters, etc.

daq2lh5.orca.orca_flashcam.get_board_id(key)¶

Return type:: int

daq2lh5.orca.orca_flashcam.get_fc_input(key)¶

Return type:: int

daq2lh5.orca.orca_flashcam.get_fcid(key)¶

Return type:: int

daq2lh5.orca.orca_flashcam.get_key(fcid, board_id, fc_input)¶

Return type:: int

daq2lh5.orca.orca_header module¶

class daq2lh5.orca.orca_header.OrcaHeader(jsons=None, lgdo_scalar=None)¶

Bases: dict

ORCA file header object.

get_auxhw_info(orca_class_name, unique_id=-1)¶

Returns a list with all the info from the AuxHw table of the header with name orca_class_name.

Optionally, if unique_id is greater or equal to zero, only return the object for that ORCA unique ID number.

Return type:: list

get_decoder_list()¶

Return type:: list[str]

get_id_to_decoder_name_dict(shift_data_id=True)¶

Return type:: dict[int, str]

get_object_info(orca_class_name)¶

Returns a dict[crate][card] with all info from the header for each card with name orca_class_name.

Return type:: dict[int, dict[int, dict]]

get_readout_info(orca_class_name, unique_id=-1)¶

Returns a list with all the readout list info from the header with name orca_class_name.

Optionally, if unique_id is greater or equal than zero, only return the readout info for that ORCA unique ID number.

Return type:: list

get_run_number()¶

Return type:: int

set_from_lgdo(lgdo_scalar)¶

daq2lh5.orca.orca_header_decoder module¶

class daq2lh5.orca.orca_header_decoder.OrcaHeaderDecoder(header=None, **kwargs)¶

Bases: OrcaDecoder

Decodes ORCA headers.

decode_packet(packet, packet_id, rbl=None)¶

Return type:: bool

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:

Scalar

daq2lh5.orca.orca_packet module¶

Provides convenience functions for working with ORCA packets.

An ORCA packet is represented by a one-dimensional numpy.ndarray of type numpy.uint32.

daq2lh5.orca.orca_packet.get_data_id(packet, shift=True)¶

Return type:: uint32

daq2lh5.orca.orca_packet.get_n_words(packet)¶

Return type:: int

daq2lh5.orca.orca_packet.hex_dump(packet, shift_data_id=True, print_n_words=False, max_words=inf, as_int=False, as_short=False, id_dict=None, use_logging=True, return_output=False)¶

daq2lh5.orca.orca_packet.is_extended(packet)¶

Return type:: bool

daq2lh5.orca.orca_packet.is_short(packet)¶

Return type:: bool

daq2lh5.orca.orca_run_decoder module¶

class daq2lh5.orca.orca_run_decoder.ORRunDecoderForRun(header=None, **kwargs)¶

Bases: OrcaDecoder

Decoder for Run Control data written by ORCA.

decode_packet(packet, packet_id, rbl)¶

Decode the ORCA Run packet.

Format is taken from the ORCA website: Run Control

Return type:: bool

get_decoded_values(key=None)¶

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

Notes

Return type:: dict[str, Any]

daq2lh5.orca.orca_streamer module¶

class daq2lh5.orca.orca_streamer.OrcaStreamer¶

Bases: DataStreamer

Data streamer for ORCA data.

_abc_impl = <_abc._abc_data object>¶

build_packet_locs(saveloc=True)¶

close_in_stream()¶

close_stream()¶

Close this data stream.

Note

Needs to be overloaded.

count_packets(saveloc=True)¶

Return type:: int

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[OrcaDecoder]

hex_dump(stream_name, n_packets=inf, skip_header=False, shift_data_id=True, print_n_words=False, max_words=inf, as_int=False, as_short=False)¶

is_orca_stream()¶

Return type:: bool

load_packet(index=None, whence=0, skip_unknown_ids=False)¶

Loads the next packet into the internal buffer.

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

Parameters:

index (int | None) – Optionally give an index of packet to skip to, relative to the “whence” location. Can be positive or negative. If out-of-range for the file, None will be returned.
whence (int) – used when an index is supplied. Follows the file.seek() convention: whence = 0 (default) means index is relative to the beginning of the file; whence = 1 means index is relative to the current position in the file; whence = 2 means relative to the end of the file.

Returns:

packet – a view of the internal buffer spanning the packet data (uint32 ndarray). If you want to hold on to the packet data while you load more packets, you can call copy() on the view to make a copy.

Return type:

ndarray | None

load_packet_header()¶

Loads the packet header at the current read location into the buffer

and updates internal variables.

Return type:: ndarray | None

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

Initialize the ORCA data stream.

Parameters:

stream_name (str) – The ORCA 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 ORCA header.

Return type:

list[RawBuffer]

read_packet()¶

Read a packet of data.

Data written to the rb_lib attribute.

Return type:: bool

set_in_stream(stream_name)¶

skip_packet(n=1)¶

Skip a packets without loading it into the internal buffer.

Requires loading the header. Optionally skips n packets.

Returns:: succeeded – returns False if reached EOF, otherwise returns true
Return type:: bool

daq2lh5.orca.skim_orca_file module¶

daq2lh5.orca.skim_orca_file.skim_orca_file()¶