Detector properties

Top-level functions

Environment([temperature, wavelength])	Environmental attributes of the detector.
Characteristics([quantum_efficiency, ...])	Characteristic attributes of the detector.
Geometry(row, col[, total_thickness, ...])	Geometrical attributes of the detector.
ReadoutProperties(times[, start_time, ...])	Readout sampling detector properties related to the readout process of a detector.
Channels(matrix, readout_position)	Updated Channels class with their matrix layout and corresponding readout positions.
Matrix(data)	Class to store and validate the 1D or 2D matrix structure.
ReadoutPosition(positions)	Class to store and validate the mapping between channel names and their physical readout positions.

Detector attributes

The detector attribute and data structure subpackage.

class pyxel.detectors.Environment(temperature=None, wavelength=None)

Bases: object

Environmental attributes of the detector.

Parameters:

• temperature (float, optional) – Temperature of the detector. Unit: K

• wavelength (float, WavelengthHandling, optional) – Information about multi-wavelength. Unit: nm

property temperature

Get Temperature of the detector.

property wavelength

Get wavelength of the detector.

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

to_dict()

Get the attributes of this instance as a dict.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

class pyxel.detectors.Characteristics(quantum_efficiency=None, charge_to_volt_conversion=None, pre_amplification=None, full_well_capacity=None, adc_bit_resolution=None, adc_voltage_range=None)

Bases: object

Characteristic attributes of the detector.

Parameters:

• quantum_efficiency (float, optional) – Quantum efficiency.

• charge_to_volt_conversion (float, optional) – Sensitivity of charge readout. Unit: V/e-

• pre_amplification (float, optional) – Gain of pre-amplifier. Unit: V/V

• full_well_capacity (float, optional) – Full well capacity. Unit: e-

• adc_voltage_range (tuple of floats, optional) – ADC voltage range. Unit: V

• adc_bit_resolution (int, optional) – ADC bit resolution.

initialize(geometry)

property quantum_efficiency

Get Quantum efficiency.

property charge_to_volt_conversion

Get charge to volt conversion parameter.

property channels_gain

property pre_amplification

Get voltage pre-amplification gain.

property adc_bit_resolution

Get bit resolution of the Analog-Digital Converter.

property adc_voltage_range

Get voltage range of the Analog-Digital Converter.

property full_well_capacity

Get Full well capacity.

property system_gain

Get system gain.

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

to_dict()

Get the attributes of this instance as a dict.

classmethod from_dict(dct)

Create a new instance from a dict.

class pyxel.detectors.Geometry(row, col, total_thickness=None, pixel_vert_size=None, pixel_horz_size=None, pixel_scale=None, channels=None)

Bases: object

Geometrical attributes of the detector.

Parameters:

• row (int) – Number of pixel rows.

• col (int) – Number of pixel columns.

• total_thickness (float, optional) – Thickness of detector. Unit: um

• pixel_vert_size (float, optional) – Vertical dimension of pixel. Unit: um

• pixel_horz_size (float, optional) – Horizontal dimension of pixel. Unit: um

• pixel_scale (float, optional) – Dimension of how much of the sky is covered by one pixel. Unit: arcsec/pixel

• channels (Channels, None) – Channel layout for the detector, including number of channels, position, and readout direction.

property row

Get Number of pixel rows.

property col

Get Number of pixel columns.

property shape

Return detector shape.

property total_thickness

Get Thickness of detector.

property pixel_vert_size

Get Vertical dimension of pixel.

property pixel_horz_size

Get Horizontal dimension of pixel.

property pixel_scale

Get pixel scale.

property horz_dimension

Get total horizontal dimension of detector. Calculated automatically.

Returns:

float – horizontal dimension

property vert_dimension

Get total vertical dimension of detector. Calculated automatically.

Returns:

float – vertical dimension

vertical_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

horizontal_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

get_channel_coord(channel)

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

to_dict()

Get the attributes of this instance as a dict.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

class pyxel.detectors.ReadoutProperties(times, start_time=0.0, non_destructive=False)

Bases: object

Readout sampling detector properties related to the readout process of a detector.

These properties include sampling times, readout steps, and other simulation parameters.

Parameters:

• times (Sequence[Number]) – A sequence of increasing numerical values representing the times at which the detector samples are read.

• start_time (float, optional. default: 0.0) – The start time for the readout process. All value in times must be greater that start_time.

• non_destructive (bool, optional. Default: False) – A boolean flag indicating whether the readout simulation is non-destructive. If set to True, the readout process will not modify the underlying data.

Examples

>>> readout_properties = ReadoutProperties(times=[1, 2, 4, 7, 10], start_time=0.0)
>>> readout_properties.times
array([ 1.,  2.,  4.,  7., 10.])
>>> readout_properties.steps
array([0., 1., 2., 3., 3.])
>>> readout_properties.num_steps
5
>>> readout_properties.absolute_time
0.0

property times

Return the sampling times for readout process.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.times
array([ 1.,  2.,  4.,  7., 10.])

property steps

Return the time interval between consecutive readout samples.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.steps
array([0., 1., 2., 3., 3.])

property num_steps

Return the total number of readout steps.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.num_steps
5

property start_time

Get the start time for the readout simulation.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.start_time
0.0

property end_time

Return the last time in the readout sequence.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.end_time
10.0

property non_destructive

Check if the readout process is non-destructive.

Returns:

bool – True if the readout does not alter the underlying data. False otherwise.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.non_destructive
False

property times_linear

Check if the time intervals between readout samples are uniform.

Returns:

bool – True is all readout steps are equal (i.e., time intervals are linear), False otherwise.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 4, 7, 10], start_time=0.0
... )
>>> readout_properties.times_linear
False

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.0
... )
>>> readout_properties.times_linear
True

property time

Get the current time within the readout simulation.

Returns:

float – The current time during the readout process.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.time
0.0

property absolute_time

Get the absolute time relative to the simulation start.

Returns:

float – The absolute time, calculated as start_time + time.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.absolute_time
0.5

property time_step

Get the step size used for advancing in the simulation.

Returns:

float – The current time step value for advancing time.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.time_step = 1.0

property read_out

Get the status of the readout process.

Returns:

bool – True if the readout process is active, False otherwise.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.read_out
True

property pipeline_count

Get the current readout pipeline count.

This count indicates the number of times the readout process has advanced.

Returns:

int – The number of completed readout steps.

property is_first_readout

Check if the current step is the first readout time.

Returns:

bool – True if this is the first readout time, False otherwise.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.is_first_readout
True

property is_last_readout

Check if the current step is the last readout time.

Returns:

bool – True if this is the last readout time, False otherwise.

Examples

>>> readout_properties = ReadoutProperties(
...     times=[1, 2, 3, 4, 5], start_time=0.5
... )
>>> readout_properties.is_last_readout
False

Channels

Sub-package to handle and validate matrix structures and readout positions for multi-channels detectors.

Example of four channels

In this example four channels OP9, OP13, OP1 and OP5 are defined in a matrix configuration as follows:

The corresponding YAML definition could be:

geometry:
   row: 1028
   col: 1024
   channels:
     matrix: [[OP9, OP13],
              [OP1, OP5 ]]
     readout_position:
       - OP9:  top-left
       - OP13: top-left
       - OP1:  bottom-left
       - OP5:  bottom-left

class pyxel.detectors.channels.Channels(matrix, readout_position)

Bases: object

Updated Channels class with their matrix layout and corresponding readout positions.

Examples

>>> channels = Channels(
...     matrix=Matrix([["OP9", "OP13"], ["OP1", "OP5"]]),
...     readout_position=ReadoutPosition(
...         {
...             "OP9": "top-left",
...             "OP13": "top-left",
...             "OP1": "bottom-left",
...             "OP5": "bottom-left",
...         }
...     ),
... )
>>> channels
Channels<4 channels>

build_mask()

Generate a mask or map for the defined channels.

to_dict()

Get the attributes of this instance as a dict.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

class pyxel.detectors.channels.Matrix(data)

Bases: object

Class to store and validate the 1D or 2D matrix structure.

Examples

>>> matrix = Matrix([["OP9", "OP13"], ["OP1", "OP5"]])
>>> matrix.shape
(2, 2)
>>> matrix.size
4

property size

Return number of elements in the matrix.

property shape

Shape of the matrix.

class pyxel.detectors.channels.ReadoutPosition(positions)

Bases: object

Class to store and validate the mapping between channel names and their physical readout positions.

Examples

>>> positions = ReadoutPosition(
...     positions={
...         "OP9": "top-left",
...         "OP13": "top-left",
...         "OP1": "bottom-left",
...         "OP5": "bottom-left",
...     }
... )

>>> len(positions)
4

>>> list(positions)
['OP9', 'OP13', 'OP1', 'OP5']

>>> positions["OP9"]
'top_left'

VALID_POSITIONS = ('top-left', 'top-right', 'bottom-left', 'bottom-right')

keys()

Return the keys of the readout positions.

CCD specific

CCD specific classes.

class pyxel.detectors.CCDGeometry(row, col, total_thickness=None, pixel_vert_size=None, pixel_horz_size=None, pixel_scale=None, channels=None)

Bases: Geometry

Geometrical attributes of a CCD detector.

Parameters:

• row (int) – Number of pixel rows.

• col (int) – Number of pixel columns.

• total_thickness (float) – Thickness of detector. Unit: um

• pixel_vert_size (float) – Vertical dimension of pixel. Unit: um

• pixel_horz_size (float) – Horizontal dimension of pixel. Unit: um

• pixel_scale (float) – Dimension of how much of the sky is covered by one pixel. Unit: arcsec/pixel

property col

Get Number of pixel columns.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

get_channel_coord(channel)

horizontal_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

property horz_dimension

Get total horizontal dimension of detector. Calculated automatically.

Returns:

float – horizontal dimension

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

property pixel_horz_size

Get Horizontal dimension of pixel.

property pixel_scale

Get pixel scale.

property pixel_vert_size

Get Vertical dimension of pixel.

property row

Get Number of pixel rows.

property shape

Return detector shape.

to_dict()

Get the attributes of this instance as a dict.

property total_thickness

Get Thickness of detector.

property vert_dimension

Get total vertical dimension of detector. Calculated automatically.

Returns:

float – vertical dimension

vertical_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

CMOS specific

CMOS specific classes.

class pyxel.detectors.CMOSGeometry(row, col, total_thickness=None, pixel_vert_size=None, pixel_horz_size=None, pixel_scale=None, channels=None)

Bases: Geometry

Geometrical attributes of a CMOS-based detector.

Parameters:

• row (int) – Number of pixel rows.

• col (int) – Number of pixel columns.

• total_thickness (float) – Thickness of detector. Unit: um

• pixel_vert_size (float) – Vertical dimension of pixel. Unit: um

• pixel_horz_size (float) – Horizontal dimension of pixel. Unit: um

• pixel_scale (float) – Dimension of how much of the sky is covered by one pixel. Unit: arcsec/pixel

property col

Get Number of pixel columns.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

get_channel_coord(channel)

horizontal_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

property horz_dimension

Get total horizontal dimension of detector. Calculated automatically.

Returns:

float – horizontal dimension

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

property pixel_horz_size

Get Horizontal dimension of pixel.

property pixel_scale

Get pixel scale.

property pixel_vert_size

Get Vertical dimension of pixel.

property row

Get Number of pixel rows.

property shape

Return detector shape.

to_dict()

Get the attributes of this instance as a dict.

property total_thickness

Get Thickness of detector.

property vert_dimension

Get total vertical dimension of detector. Calculated automatically.

Returns:

float – vertical dimension

vertical_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

MKID specific

MKID specific classes.

class pyxel.detectors.MKIDGeometry(row, col, total_thickness=None, pixel_vert_size=None, pixel_horz_size=None, pixel_scale=None, channels=None)

Bases: Geometry

Geometrical attributes of a MKID-based detector.

Parameters:

• row (int) – Number of pixel rows.

• col (int) – Number of pixel columns.

• total_thickness (float) – Thickness of detector. Unit: um

• pixel_vert_size (float) – Vertical dimension of pixel. Unit: um

• pixel_horz_size (float) – Horizontal dimension of pixel. Unit: um

• pixel_scale (float) – Dimension of how much of the sky is covered by one pixel. Unit: arcsec/pixel

property col

Get Number of pixel columns.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

get_channel_coord(channel)

horizontal_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

property horz_dimension

Get total horizontal dimension of detector. Calculated automatically.

Returns:

float – horizontal dimension

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

property pixel_horz_size

Get Horizontal dimension of pixel.

property pixel_scale

Get pixel scale.

property pixel_vert_size

Get Vertical dimension of pixel.

property row

Get Number of pixel rows.

property shape

Return detector shape.

to_dict()

Get the attributes of this instance as a dict.

property total_thickness

Get Thickness of detector.

property vert_dimension

Get total vertical dimension of detector. Calculated automatically.

Returns:

float – vertical dimension

vertical_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

APD specific

APD specific classes.

class pyxel.detectors.APDCharacteristics(roic_gain, quantum_efficiency=None, full_well_capacity=None, adc_bit_resolution=None, adc_voltage_range=None, avalanche_gain=None, pixel_reset_voltage=None, common_voltage=None)

Bases: object

Characteristic attributes of the APD detector.

Parameters:

• roic_gain – Gain of the read-out integrated circuit. Unit: V/V

• quantum_efficiency (float, optional) – Quantum efficiency.

• full_well_capacity (float, optional) – Full well capacity. Unit: e-

• adc_bit_resolution (int, optional) – ADC bit resolution.

• adc_voltage_range (tuple of floats, optional) – ADC voltage range. Unit: V

• avalanche_gain (float, optional) – APD gain. Unit: electron/electron

• pixel_reset_voltage (float) – DC voltage going into the detector, not the voltage of a reset pixel. Unit: V

• common_voltage (float) – Common voltage. Unit: V

initialize(geometry)

property quantum_efficiency

Get Quantum efficiency.

property avalanche_gain

Get APD gain.

property pixel_reset_voltage

Get pixel reset voltage.

property common_voltage

Get common voltage.

property avalanche_bias

Get avalanche bias.

property roic_gain

Get roic gainn.

property node_capacitance

Get node capacitance.

property charge_to_volt_conversion

Get charge to voltage conversion factor.

property adc_bit_resolution

Get bit resolution of the Analog-Digital Converter.

property adc_voltage_range

Get voltage range of the Analog-Digital Converter.

property full_well_capacity

Get Full well capacity.

property system_gain

Get system gain.

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

static bias_to_node_capacitance_saphira(bias)

Pixel integrating node capacitance in F.

The below interpolates empirical published data, however note that Node C = Charge Gain / Voltage Gain So can be calculated by measuring V gain (varying PRV) and chg gain (PTC); see [2]

Parameters:

bias (float)

Returns:

output_capacitance (float)

static bias_to_gain_saphira(bias)

Calculate gain from bias.

The formula ignores the soft knee between the linear and unity gain ranges, but should be close enough. [2] (Mk13 ME1000)

Parameters:

bias (float)

Returns:

float – gain

static gain_to_bias_saphira(gain)

Calculate bias from gain.

The formula ignores the soft knee between the linear and unity gain ranges, but should be close enough. [2] (Mk13 ME1000)

Parameters:

gain (float)

Returns:

bias (float)

static detector_gain_saphira(capacitance, roic_gain)

Saphira detector gain.

Parameters:

• capacitance (float)

• roic_gain (float)

Returns:

float

to_dict()

Get the attributes of this instance as a dict.

classmethod from_dict(dct)

Create a new instance from a dict.

class pyxel.detectors.APDGeometry(row, col, total_thickness=None, pixel_vert_size=None, pixel_horz_size=None, pixel_scale=None, channels=None)

Bases: Geometry

Geometrical attributes of a APD-based detector.

Parameters:

• row (int) – Number of pixel rows.

• col (int) – Number of pixel columns.

• total_thickness (float) – Thickness of detector. Unit: um

• pixel_vert_size (float) – Vertical dimension of pixel. Unit: um

• pixel_horz_size (float) – Horizontal dimension of pixel. Unit: um

property col

Get Number of pixel columns.

classmethod from_dict(dct)

Create a new instance of Geometry from a dict.

get_channel_coord(channel)

horizontal_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.

property horz_dimension

Get total horizontal dimension of detector. Calculated automatically.

Returns:

float – horizontal dimension

property numbytes

Recursively calculates object size in bytes using Pympler library.

Returns:

int – Size of the object in bytes.

property pixel_horz_size

Get Horizontal dimension of pixel.

property pixel_scale

Get pixel scale.

property pixel_vert_size

Get Vertical dimension of pixel.

property row

Get Number of pixel rows.

property shape

Return detector shape.

to_dict()

Get the attributes of this instance as a dict.

property total_thickness

Get Thickness of detector.

property vert_dimension

Get total vertical dimension of detector. Calculated automatically.

Returns:

float – vertical dimension

vertical_pixel_center_pos_list()

Generate horizontal position list of all pixel centers in detector imaging area.