`hexsample.readout` — Readout facilities#

This module contains…

Digitization process#

Module documentation#

Readout facilities.

class hexsample.readout.HexagonalReadoutMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Enum class expressing the possible readout strategies.

SPARSE = 'SPARSE'#

RECTANGULAR = 'RECTANGULAR'#

CIRCULAR = 'CIRCULAR'#

class hexsample.readout.HexagonalReadoutBase(layout: HexagonalLayout, num_cols: int, num_rows: int, pitch: float, enc: float, gain: float)#

Description of a pixel readout chip on a hexagonal matrix.

Parameters:

layout (HexagonalLayout) – The layout of the hexagonal matrix.
num_cols (int) – The number of columns in the readout.
num_rows (int) – The number of rows in the readout.
pitch (float) – The readout pitch in cm.
enc (float) – The equivalent noise charge in electrons.
gain (float) – The readout gain in ADC counts per electron.

static discriminate(array: ndarray, threshold: float) → ndarray#

Utility function acting as a simple constant-threshold discriminator over a generic array. This returns a boolean mask with True for all the array elements larger than the threshold.

This is intented to avoid possible confusion between strict and loose comparison operators (e.g., < vs <=) when comparing the content of an array with a threshold, and all functions downstream doing this (e.g., zero_suppress) should use this and refrain from re-implementing their own logic.

static zero_suppress(array: ndarray, threshold: float) → None#

Utility function to zero-suppress a generic array.

This is returning an array of the same shape of the input where all the values lower or equal than the zero suppression threshold are set to zero.

Parameters:

array (array_like) – The input array.
threshold (float) – The zero suppression threshold.

static latch_timestamp(timestamp: float) → Tuple[int, int, int]#

Latch the event timestamp and return the corresponding fields of the digi event contribution: seconds, microseconds and livetime.

Warning

The livetime calculation is not implemented, yet.

Parameters:: timestamp (float) – The ground-truth event timestamp from the event generator.

digitize(pha: ndarray, zero_sup_threshold: int = 0, offset: int = 0) → ndarray#

Digitize the actual signal.

Parameters:

pha (array_like) – The input array of pixel signals to be digitized.
zero_sup_threshold (int) – Zero-suppression threshold in ADC counts.
offset (int) – Optional offset in ADC counts to be applied before the zero suppression.

class hexsample.readout.HexagonalReadoutSparse(layout: HexagonalLayout, num_cols: int, num_rows: int, pitch: float, enc: float, gain: float)#

Description of a pixel sparse readout chip on a hexagonal matrix. In the following readout, no ROI is formed, every (and only) triggered pixel of the event is kept with its positional information in (col, row) format on the hexagonal grid.

Parameters:

layout (HexagonalLayout) – The layout of the hexagonal matrix.
num_cols (int) – The number of columns in the readout.
num_rows (int) – The number of rows in the readout.
pitch (float) – The readout pitch in cm.
enc (float) – The equivalent noise charge in electrons.
gain (float) – The readout gain in ADC counts per electron.

read(timestamp: float, x: ndarray, y: ndarray, trg_threshold: float, zero_sup_threshold: int = 0, offset: int = 0) → DigiEventSparse#

Sparse readout an event.

Parameters:

timestamp (float) – The event timestamp.
x (array_like) – The physical x coordinates of the input charge.
y (array_like) – The physical x coordinates of the input charge.
trg_threshold (float) – Trigger threshold in electron equivalent.
zero_sup_threshold (int) – Zero suppression threshold in ADC counts.
offset (int) – Optional offset in ADC counts to be applied before the zero suppression.

class hexsample.readout.HexagonalReadoutRectangular(layout: HexagonalLayout, num_cols: int, num_rows: int, pitch: float, enc: float, gain: float)#

Description of a pixel readout chip on a hexagonal matrix.

static sum_miniclusters(array: ndarray) → ndarray#

Sum the values in a given numpy array over its 2 x 2 trigger miniclusters.

Note that the shape of the target 2-dimensional array must be even in both dimensions for the thing to work.

static is_odd(value: int) → bool#

Return whether the input integer is odd.

See https://stackoverflow.com/questions/14651025/ for some metrics about the speed of this particular implementation.

static is_even(value: int) → bool#: Return whether the input integer is even.

sample(x: ndarray, y: ndarray) → Tuple[Tuple[int, int], ndarray]#

Spatially sample a pair of arrays of x and y coordinates in physical space onto logical (hexagonal) coordinates in logical space.

This is achieved by converting the (x, y) physical coordinates into the corresponding (col, row) logical coordinates on the hexagonal grid, and then filling a two-dimensional histogram in logical space.

Note

The output two-dimensional histogram is restricted to the pixels with a physical signal, in order to avoid having to deal with large sparse arrays downstream. See lucabaldini/hexsample#12 for more details about the reasoning behind this.

Parameters:

x (array_like) – The physical x coordinates to sample.
y (array_like) – The physical y coordinates to sample.

Returns:

min_col, min_row, signal – The coordinates of the bottom-left corner of the smallest rectangle containing all the signal, and the corresponding histogram of the signal itself, in electron equivalent.

Return type:

3-element tuple (2 integers and an array)

trigger(signal: ndarray, trg_threshold, min_col: int, min_row: int, padding: Padding) → Tuple[RegionOfInterest, ndarray]#: Apply the trigger, calculate the region of interest, and pad the signal array to the proper dimension.

Warning

This is still incorrect at the edges of the readout chip, as we are not trimming the ROI (and the corresponding arrays) to the physical dimensions of the chip.

read(timestamp: float, x: ndarray, y: ndarray, trg_threshold: float, padding: Padding, zero_sup_threshold: int = 0, offset: int = 0) → DigiEventRectangular#

Readout an event.

Parameters:

timestamp (float) – The event timestamp.
x (array_like) – The physical x coordinates of the input charge.
y (array_like) – The physical x coordinates of the input charge.
trg_threshold (float) – Trigger threshold in electron equivalent.
padding (Padding) – The padding to be applied to the ROT.
zero_sup_threshold (int) – Zero suppression threshold in ADC counts.
offset (int) – Optional offset in ADC counts to be applied before the zero suppression.

class hexsample.readout.Xpol3(enc: float = 20.0, gain: float = 1.0)#: Derived class representing the XPOL-III readout chip.

class hexsample.readout.HexagonalReadoutCircular(layout: HexagonalLayout, num_cols: int, num_rows: int, pitch: float, enc: float, gain: float)#

Description of a pixel circular readout chip on a hexagonal matrix. In the following readout, the maximum PHA pixel is found and the ROI formed by that pixel and its 6 adjacent neighbours. The standard shape of columns, rows and pha array is then 7, except for events on border, that will have len<7.

Parameters:

layout (HexagonalLayout) – The layout of the hexagonal matrix.
num_cols (int) – The number of columns in the readout.
num_rows (int) – The number of rows in the readout.
pitch (float) – The readout pitch in cm.
enc (float) – The equivalent noise charge in electrons.
gain (float) – The readout gain in ADC counts per electron.

NUM_PIXELS = 7#

read(timestamp: float, x: ndarray, y: ndarray, trg_threshold: float, zero_sup_threshold: int = 0, offset: int = 0) → DigiEventCircular#

Circular readout an event.

Parameters:

timestamp (float) – The event timestamp.
x (float) – The physical x coordinate of the highest pha pixel.
y (float) – The physical y coordinate of the highest pha pixel.
trg_threshold (float) – Trigger threshold in electron equivalent.
zero_sup_threshold (int) – Zero suppression threshold in ADC counts.
offset (int) – Optional offset in ADC counts to be applied before the zero suppression.

hexsample.readout._readout_class(mode: HexagonalReadoutMode) → type#: Return the proper class to be used to instantiate a readout chip for a given readout mode.

hexsample.readout.readout_chip(mode: HexagonalReadoutMode, *args, **kwargs)#: Return an instance of the proper readout chip for a given readout mode.

hexsample.readout — Readout facilities#

Digitization process#

Module documentation#

`hexsample.readout` — Readout facilities#