readout — Readout facilities

This module contains…

Digitization process

Module documentation

Readout facilities.

class hexsample.readout.AbstractReadout

Abstract base class for a generic pixel readout chip.

This is a simple abstract class defining the a single static method read(), along with the associated signature, that all readout chips must implement.

abstractmethod read(timestamp: float, x: ndarray, y: ndarray, offset: int = 0) → DigiEventBase

Readout a single event, given the input coordinates of the charge.

Arguments

timestampfloat

The event timestamp.

xarray_like

The physical x coordinates of the input charge.

yarray_like

The physical y coordinates of the input charge.

offsetint

Optional offset in ADC counts to be applied before the zero suppression.

_abc_impl = <_abc._abc_data object>

class hexsample.readout.HexagonalReadoutBase(layout: HexagonalLayout = HexagonalLayout.ODD_R, num_cols: int = 304, num_rows: int = 352, pitch: float = 0.005, enc: float = 30.0, gain: float = 1.0, trg_threshold: float = 500.0, zero_sup_threshold: int = 0)

Description of a pixel readout chip on a hexagonal matrix.

Note that, in addition to the physical properties (noise and gain) the readout chip comes up at creation time with a well defined configuration, in terms of trigger and zero-suppression thresholds. Arguably, in the future we might add the possibility to change these parameters at runtime to make things more germane to what happens in real life, but for the time being that seems hardly necessary.

Also note the readout chip inherits all the members from HexagonalGrid.

Arguments

encfloat

The equivalent noise charge in electrons.

gainfloat

The readout gain in ADC counts per electron (default 1, which means that the PHA you get out are the electrons collected).

trg_thresholdfloat

Trigger threshold in electron equivalent (note this is a float because it is expressed in physical space, not in electronics space).

zero_sup_thresholdint

Zero suppression threshold in ADC counts.

enc: float = 30.0

gain: float = 1.0

trg_threshold: float = 500.0

zero_sup_threshold: int = 0

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.

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.

Note this is a static method that can be used interchangeably, e.g., to operate on the pulse height array or the trigger signal array.

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.

Note this is a static method that can be used interchangeably, e.g., to operate on the pulse height array or the trigger signal array.

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, offset: int = 0) → ndarray

Digitize the actual signal.

Arguments

phaarray_like

The input array of pixel signals to be digitized.

offsetint

Optional offset in ADC counts to be applied before the zero suppression.

_abc_impl = <_abc._abc_data object>

class hexsample.readout.HexagonalReadoutCircular(layout: HexagonalLayout = HexagonalLayout.ODD_R, num_cols: int = 304, num_rows: int = 352, pitch: float = 0.005, enc: float = 30.0, gain: float = 1.0, trg_threshold: float = 500.0, zero_sup_threshold: int = 0)

Fixed 7-pixel ROI readout chip on a hexagonal matrix.

This class mimics a readout chip with a fixed 7-pixel ROI on a hexagonal matrix, where the maximum PHA is found and the ROI formed by that pixel and its 6 adjacent neighbours.

Note events on border will have less than 7 pixels.

NUM_PIXELS = 7

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

Overloaded method.

_abc_impl = <_abc._abc_data object>

class hexsample.readout.HexagonalReadoutRectangular(layout: HexagonalLayout = HexagonalLayout.ODD_R, num_cols: int = 304, num_rows: int = 352, pitch: float = 0.005, enc: float = 30.0, gain: float = 1.0, trg_threshold: float = 500.0, zero_sup_threshold: int = 0, padding: Padding = Padding(top=2, right=2, bottom=2, left=2))

ROI-based readout chip on a hexagonal matrix.

This mimics the functionality of the various generations of XPOL readout chips, where a ROT (region of trigger) is automatically defines based on the 2 x 2 minicluster trigger logic, and then expanded with a configurable padding to form the ROI (region of interest) that is actually read out.

padding: Padding = Padding(top=2, right=2, bottom=2, left=2)

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.

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, min_col: int, min_row: int) → 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, offset: int = 0) → DigiEventRectangular

Overloaded method.

_abc_impl = <_abc._abc_data object>

class hexsample.readout.HexagonalReadoutMode(*values)

Enum class expressing the possible readout strategies.

RECTANGULAR = 'rectangular'

CIRCULAR = 'circular'

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.