readout — Readout facilities

This module contains…

Digitization process

Module documentation

Readout facilities.

class hexsample.readout.HexagonalReadoutMode(*values)

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.

Arguments

layoutHexagonalLayout

The layout of the hexagonal matrix.

num_colsint

The number of columns in the readout.

num_rowsint

The number of rows in the readout.

pitchfloat

The readout pitch in cm.

encfloat

The equivalent noise charge in electrons.

gainfloat

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.

Arguments

arrayarray_like

The input array.

thresholdfloat

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.

Arguments

timestampfloat

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.

Arguments

phaarray_like

The input array of pixel signals to be digitized.

zero_sup_thresholdint

Zero-suppression threshold in ADC counts.

offsetint

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.

Arguments

layoutHexagonalLayout

The layout of the hexagonal matrix.

num_colsint

The number of columns in the readout.

num_rowsint

The number of rows in the readout.

pitchfloat

The readout pitch in cm.

encfloat

The equivalent noise charge in electrons.

gainfloat

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.

Arguments

timestampfloat

The event timestamp.

xarray_like

The physical x coordinates of the input charge.

yarray_like

The physical x coordinates of the input charge.

trg_thresholdfloat

Trigger threshold in electron equivalent.

zero_sup_thresholdint

Zero suppression threshold in ADC counts.

offsetint

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 https://github.com/lucabaldini/hexsample/issues/12 for more details about the reasoning behind this.

Arguments

xarray_like

The physical x coordinates to sample.

yarray_like

The physical y coordinates to sample.

Returns

min_col, min_row, signal3-element tuple (2 integers and an array)

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.

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.

Arguments

timestampfloat

The event timestamp.

xarray_like

The physical x coordinates of the input charge.

yarray_like

The physical x coordinates of the input charge.

trg_thresholdfloat

Trigger threshold in electron equivalent.

paddingPadding

The padding to be applied to the ROT.

zero_sup_thresholdint

Zero suppression threshold in ADC counts.

offsetint

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.

Arguments

layoutHexagonalLayout

The layout of the hexagonal matrix.

num_colsint

The number of columns in the readout.

num_rowsint

The number of rows in the readout.

pitchfloat

The readout pitch in cm.

encfloat

The equivalent noise charge in electrons.

gainfloat

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.

Arguments

timestampfloat

The event timestamp.

xfloat

The physical x coordinate of the highest pha pixel.

yfloat

The physical y coordinate of the highest pha pixel.

trg_thresholdfloat

Trigger threshold in electron equivalent.

zero_sup_thresholdint

Zero suppression threshold in ADC counts.

offsetint

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.