pygama.raw.orca package#

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

Submodules#

pygama.raw.orca.orca_base module#

class pygama.raw.orca.orca_base.OrcaDecoder(header: Optional[OrcaHeader] = 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: OrcaHeader) → None#

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

pygama.raw.orca.orca_base.get_card(ccc: int) → int#

Get card number back from hash value.

pygama.raw.orca.orca_digitizers module#

class pygama.raw.orca.orca_digitizers.ORSIS3302DecoderForEnergy(header: Optional[OrcaHeader] = None, **kwargs)#

Bases: OrcaDecoder

Decoder for Struck SIS3302 digitizer data written by ORCA.

decode_packet(packet: ndarray[Any, dtype[uint32]], packet_id: int, rbl: RawBufferLibrary) → bool#

Return type:: bool

get_decoded_values(key: Optional[int] = None) → dict[str, Any]#

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_list() → list[str]#

Overload with list of keys for this decoder, e.g. return range(n_channels). The default version works for decoders with single / no keys.

Return type:: list[str]

set_header(header: OrcaHeader) → None#

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

class pygama.raw.orca.orca_digitizers.ORSIS3316WaveformDecoder(header: Optional[OrcaHeader] = None, **kwargs)#

Bases: OrcaDecoder

Decoder for Struck SIS3316 digitizer data written by ORCA.

decode_packet(packet: ndarray[Any, dtype[uint32]], packet_id: int, rbl: RawBufferLibrary) → bool#

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

get_decoded_values(key: Optional[int] = None) → dict[str, Any]#

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

Notes

Return type:: dict[str, Any]

get_key_list() → list[int]#

Overload with list of keys for this decoder, e.g. return range(n_channels). The default version works for decoders with single / no keys.

Return type:: list[int]

set_header(header: OrcaHeader) → None#

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

pygama.raw.orca.orca_flashcam module#

class pygama.raw.orca.orca_flashcam.ORFlashCamADCWaveformDecoder(header: Optional[OrcaHeader] = None, **kwargs)#

Bases: OrcaDecoder

Decoder for FlashCam ADC data written by ORCA.

assert_nsamples(nsamples: int, fcid: int) → None#

decode_packet(packet: ndarray[Any, dtype[uint32]], packet_id: int, rbl: RawBufferLibrary) → bool#

Decode the ORCA FlashCam ADC packet.

Return type:: bool

get_decoded_values(key: Optional[int] = None) → dict[str, Any]#

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

Notes

Return type:: dict[str, Any]

get_key_list() → list[int]#

Overload with list of keys for this decoder, e.g. return range(n_channels). The default version works for decoders with single / no keys.

Return type:: list[int]

set_header(header: OrcaHeader) → None#

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

class pygama.raw.orca.orca_flashcam.ORFlashCamListenerConfigDecoder(header: Optional[OrcaHeader] = None, **kwargs)#

Bases: OrcaDecoder

Decoder for FlashCam listener config written by ORCA.

decode_packet(packet: ndarray[Any, dtype[uint32]], packet_id: int, rbl: RawBufferLibrary) → bool#

Return type:: bool

get_decoded_values(key: Optional[int] = None) → dict[str, Any]#

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

Notes

Return type:: dict[str, Any]

class pygama.raw.orca.orca_flashcam.ORFlashCamListenerStatusDecoder(header: Optional[OrcaHeader] = 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.

pygama.raw.orca.orca_flashcam.get_ch(key: int) → int#

Return type:: int

pygama.raw.orca.orca_flashcam.get_fcid(key: int) → int#

Return type:: int

pygama.raw.orca.orca_flashcam.get_key(fcid, ch: int) → int#

Return type:: int

pygama.raw.orca.orca_header module#

class pygama.raw.orca.orca_header.OrcaHeader(jsons: Optional[str] = None, lgdo_scalar: Optional[Scalar] = None)#

Bases: dict

ORCA file header object.

get_auxhw_info(orca_class_name: str, unique_id: int = -1) → list#

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_data_id(decoder_name: str) → int#

Return type:: int

get_decoder_list() → list[str]#

Return type:: list[str]

get_id_to_object_name_dict(shift_data_id: bool = True) → dict[int, str]#

Return type:: dict[int, str]

get_object_info(orca_class_name: str) → dict[int, dict[int, dict]]#

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: str, unique_id: int = -1) → list#

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() → int#

Return type:: int

set_from_lgdo(lgdo_scalar: Scalar) → None#

pygama.raw.orca.orca_header_decoder module#

class pygama.raw.orca.orca_header_decoder.OrcaHeaderDecoder(header: Optional[OrcaHeader] = None, **kwargs)#

Bases: OrcaDecoder

Decodes ORCA headers.

buffer_is_full(rb: RawBuffer) → bool#

Returns whether the buffer is too full to read in another packet.

Return type:: bool

decode_packet(packet: ndarray[Any, dtype[uint32]], packet_id: int, rbl: Optional[RawBufferLibrary] = None) → bool#

Return type:: bool

make_lgdo(key: Optional[int] = None, size: Optional[int] = None) → Scalar#

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 (Optional[int]) – 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 (Optional[int]) – the size to be allocated for the LGDO, if applicable.

Returns:

data_obj – the newly allocated LGDO.

Return type:

Scalar

pygama.raw.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.

pygama.raw.orca.orca_packet.get_data_id(packet: ndarray[Any, dtype[uint32]], shift: bool = True) → uint32#

Return type:: uint32

pygama.raw.orca.orca_packet.get_n_words(packet: ndarray[Any, dtype[uint32]]) → int#

Return type:: int

pygama.raw.orca.orca_packet.hex_dump(packet: ndarray[Any, dtype[uint32]], shift_data_id: bool = True, print_n_words: bool = False, max_words: int = inf, as_int: bool = False, as_short: bool = False, id_dict: Optional[dict] = None, use_logging: bool = True) → None#

pygama.raw.orca.orca_packet.is_short(packet: ndarray[Any, dtype[uint32]]) → bool#

Return type:: bool

pygama.raw.orca.orca_streamer module#

class pygama.raw.orca.orca_streamer.OrcaStreamer#

Bases: DataStreamer

Data streamer for ORCA data.

_abc_impl = <_abc._abc_data object>#

close_in_stream() → None#

close_stream() → None#

Close this data stream.

Note

Needs to be overloaded.

get_decoder_list() → list[pygama.raw.orca.orca_base.OrcaDecoder]#

Returns a list of decoder objects for this data stream.

Notes

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

Return type:: list[pygama.raw.orca.orca_base.OrcaDecoder]

hex_dump(stream_name: str, n_packets: int = inf, skip_header: bool = False, shift_data_id: bool = True, print_n_words: bool = False, max_words: int = inf, as_int: bool = False, as_short: bool = False) → None#

is_orca_stream() → bool#

Return type:: bool

load_packet(skip_unknown_ids: bool = False) → numpy.uint32 | None#

Loads the next packet into the internal buffer.

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

Return type:: numpy.uint32 | None

open_stream(stream_name: str, rb_lib: Optional[RawBufferLibrary] = None, buffer_size: int = 8192, chunk_mode: str = 'any_full', out_stream: str = '') → list[pygama.raw.raw_buffer.RawBuffer]#

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 (Optional[RawBufferLibrary]) – 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[pygama.raw.raw_buffer.RawBuffer]

read_packet() → bool#

Read a packet of data.

Data written to the rb_lib attribute.

Return type:: bool

set_in_stream(stream_name: str) → None#