Reference Manual 

Treat the surface as a segment centered at these aperture coordinates.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

The computation is based on surface tilt angles and assumes rotations are applied in the order (last first) Z @ Y @ X. This corresponds to rotating the surface around the telescope X axis, then the telescope Y axis and finally the telescope Z axis. The rotations follow the right-hand rule (counter-clockwise).

These angles are intended for small misalignments, while create_surface_rotation() is a more robust method. Tilt angles can be bypassed if a custom rotation matrix has been set using set_rotation_matrix() method.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

get_surface_normal_vector(x, y)

Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.

Parameters:

x (float) – x coordinate of the point.
y (float) – y coordinate of the point.

Returns:

Normal unit vector.

Return type:

np.ndarray

offset: Treat the surface as a segment centered at these aperture coordinates.

sagitta(r)

Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.

Parameters:: r (np.ndarray, list or scalar) – Radial distance(s) from the optical axis.
Returns:: Sagitta value(s) at the given radial distance(s).
Return type:: np.ndarray

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.AtmosphericTransmission(info='', value=None, wavelength=None, altitude=None)

Represents atmospheric optical depth as a function of photon wavelength and emission altitude.

info: A string containing the header/metadata from the loaded configuration file.

value: A numpy.ndarray of shape (m,n) representing the atmosphere optical depth (tau).

wavelength: A numpy.ndarray of shape (n,) representing the wavelengths in nanometers.

altitude: A numpy.ndarray of shape (m,) representing the emission altitude in millimeters.

Methods:

load_simtel_file(filepath)

Loads atmospheric optical depth data from a simtel atmospheric transimission input file.

classmethod load_simtel_file(filepath): Loads atmospheric optical depth data from a simtel atmospheric transimission input file. Automatically extracts header info and converts emission altitudes from km to mm.

class iactsim.optics.BoxSurface(half_side_x, half_side_y, half_side_z, has_top=True, has_bottom=True, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), surface_type=SurfaceType.OPAQUE, name=None)

Represents a box optical surface.

Parameters:

half_side_x (float) – Half-side of the box in the x-direction.
half_side_y (float) – Half-side of the box in the y-direction.
half_side_z (float) – Half-side of the box in the z-direction.
has_top (bool, optional) – Whether the box has a top cap, by default True.
has_bottom (bool, optional) – Whether the box has a bottom cap, by default True.
position (array-like, optional) – Position of box center [x, y, z], by default (0,0,0).
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
surface_type (SurfaceType, optional) – Type of surface (opaque or sensitive), by default SurfaceType.OPAQUE.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.CameraGeometry(telescope)

Extracts and defines the geometry of a camera system from an IACT object.

This class handles multiple camera modules (e.g., SipmTileSurface and GenericFlatModule) that make up the focal plane. It calculates the 3D position of all pixels in the telescope reference system and organizes the data into dictionaries for efficient lookup.

Parameters:: telescope (IACT) – An instance of the IACT telescope containing the optical system and camera.

pixels

A dictionary mapping pixel ID to a dictionary of its properties:

‘position’: numpy.ndarray of shape (3,) representing the [x, y, z] coordinates in the telescope reference system.

‘half_size’: float representing the half-size of the pixel.

‘shape’: ApertureShape representing the shape of the pixel.

‘module_id’: int representing the ID of the module it belongs to.

Type:: dict

modules

A dictionary mapping module ID to a dictionary of its properties:

‘type’: str representing the sensor type (‘SIPM_TILE’ or ‘GENERIC_FLAT_MODULE’).

‘pixel_ids’: list of int representing the IDs of the pixels in this module.

Type:: dict

n_pixels

The total number of pixels.

Type:: int

n_modules

The total number of modules.

Type:: int

Methods:

plot_layout([show_ids, ids_fontsize, ...])

Plots the 2D camera x-y layout in the telescope reference system.

plot_layout(show_ids=True, ids_fontsize=6., auto_adjust=True, ax=None)

Plots the 2D camera x-y layout in the telescope reference system.

Parameters:

show_ids (bool, optional) – If True, displays the pixel ID at the center of each pixel. Defaults to True.
ids_fontsize (float, optional) – The font size for the pixel ID text. Defaults to 6.0.
auto_adjust (bool, optional) – If True, dynamically scales the figure size and adjusts the drawn pixel separation to prevent visual clumping. Defaults to True.
ax (matplotlib.axes.Axes, optional) – The axis on which to plot. If None, a new figure and axis are created.

Returns:

The axis containing the plot.

Return type:

matplotlib.axes.Axes

class iactsim.optics.ConicalSurface(radius_top, radius_bottom, height, has_top=True, has_bottom=True, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), surface_type=SurfaceType.OPAQUE, name=None)

Represents a truncated conical optical surface.

Parameters:

radius_top (float) – Top radius of the cone.
radius_bottom (float) – Bottom radius of the cone.
height (float) – Height of the conde.
has_top (bool, optional) – Whether the cone has a top cap, by default True.
has_bottom (bool, optional) – Whether the cone has a bottom cap, by default True.
position (array-like, optional) – Position of cone center [x, y, z] (half-height on the cone axis), by default (0,0,0).
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
surface_type (SurfaceType, optional) – Type of surface (opaque or sensitive), by default SurfaceType.OPAQUE.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.CylindricalSurface(radius, height, has_top=True, has_bottom=True, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), surface_type=SurfaceType.OPAQUE, name=None)

Represents a cylindrical optical surface.

Parameters:

radius (float) – Radius of the cylinder.
height (float) – Height of the cylinder.
has_top (bool, optional) – Whether the cylinder has a top cap, by default True.
has_bottom (bool, optional) – Whether the cylinder has a bottom cap, by default True.
position (array-like, optional) – Position of cylinder center [x, y, z] (half-height on the cylinder axis), by default (0,0,0).
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
surface_type (SurfaceType, optional) – Type of surface (opaque or sensitive), by default SurfaceType.OPAQUE.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.FlatSurface(half_aperture, central_hole_half_aperture=0.0, aperture_shape=ApertureShape.CIRCULAR, central_hole_shape=ApertureShape.CIRCULAR, surface_type=SurfaceType.REFLECTIVE, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), scattering_dispersion=0.0, properties=None, material_in=Materials.AIR, material_out=Materials.AIR, name=None)

Represents a flat optical surface.

Parameters:

half_aperture (float) – Half-aperture of the surface.
central_hole_half_aperture (float, optional) – Half-aperture of the central hole (0.0 if no hole), by default 0.0
aperture_shape (ApertureShape, optional) – Shape of the aperture (circular, hexagonal or rectangular), by default ApertureShape.CIRCULAR
central_hole_shape (ApertureShape, optional) – Shape of the central hole (circular, hexagonal or rectangular), by default ApertureShape.CIRCULAR
surface_type (SurfaceType, optional) – Type of surface (reflective, refractive, opaque, dummy), by default SurfaceType.REFLECTIVE
position (array-like, optional) – Position of the surface center [x, y, z], by default None
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
scattering_dispersion (float, optional) – Standard deviation of Gaussian scattering after reflection/transmission, by default 0.0
properties (SurfaceProperties, optional) – Reflectance/transmittance properties of the surface, by default None
material_in (material, optional) – Material of the space before the surface front side. I.e. the material in which photons arriving with a negative z-component of their direction vector are travelling, by default standard air.
material_out (material, optional) – Material of the space after the surface back side. I.e. the material in which photons arriving with a positive z-component of their direction vector are travelling, by default standard air.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`get_surface_normal_vector`(x, y)	Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.
`sagitta`(r)	Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

Attributes:

iactsim.optics.SurfaceProperties

Treat the surface as a segment centered at these aperture coordinates.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

get_surface_normal_vector(x, y)

Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.

Parameters:

x (float) – x coordinate of the point.
y (float) – y coordinate of the point.

Returns:

Normal unit vector.

Return type:

np.ndarray

offset: Treat the surface as a segment centered at these aperture coordinates.

sagitta(r)

Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.

Parameters:: r (np.ndarray, list or scalar) – Radial distance(s) from the optical axis.
Returns:: Sagitta value(s) at the given radial distance(s).
Return type:: np.ndarray

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.FresnelSurfacePropertiesGenerator

Handles the calculation and population of SurfaceProperties objects based on Fresnel equations for a given Surface instance.

Methods:

generate(surface[, wavelengths, angles, ...])

Generate a populated SurfaceProperties object.

generate(surface, wavelengths=None, angles=None, polarization='unpolarized', inplace=False)

Generate a populated SurfaceProperties object.

Parameters:

surface (iactsim.optics.Surface) – The surface object containing material_in and material_out attributes, which must have get_refractive_index(wavelengths) methods.
wavelengths (np.ndarray, optional) – 1D array of wavelengths in nm. If None, defaults to np.arange(200, 901, 1).
angles (np.ndarray, optional) – 1D array of incidence angles in degrees. If None, defaults to np.arange(0, 91, 1).
polarization ({'unpolarized', 's', 'p', 'rs', 'rp'}, optional) – The specific polarization to compute for reflectance and transmittance. Default is ‘unpolarized’.
inplace (bool, optional) – If True, modifies the provided surface properties in place. Default is False.

Returns:

If inplace is False, a populated properties object containing the calculated matrices: - reflectance, transmittance (Front interface) - reflectance_back, transmittance_back (Back interface) - wavelength, incidence_angle vectors.

Return type:

class iactsim.optics.GenericFlatModule(pixels, half_aperture, aperture_shape=ApertureShape.SQUARE, central_hole_half_aperture=0.0, central_hole_shape=ApertureShape.SQUARE, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), scattering_dispersion=0.0, surface_type=SurfaceType.SENSITIVE, properties=None, material_in=Materials.AIR, material_out=Materials.AIR, name=None)

Represents a generic flat module with arbitrarily placed pixels.

Parameters:

pixels (List[GenericPixel]) – List of GenericPixel objects defining the layout and properties of the module pixels.
half_aperture (float) – Outer dimension (radius, inradius, or half-side) of the entire module surface (must contain all pixels).
aperture_shape (ApertureShape, optional) – The shape of the module outer aperture, by default ApertureShape.SQUARE.
central_hole_half_aperture (float, optional) – Inner dimension (hole) of the module surface, by default 0.0.
central_hole_shape (ApertureShape, optional) – The shape of the central hole, by default ApertureShape.SQUARE.
position (array-like, optional) – Position of the surface center [x, y, z], by default None
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
scattering_dispersion (float, optional) – Standard deviation of Gaussian scattering after reflection/transmission, by default 0.0
surface_type (SurfaceType, optional) – Type of the sensitive surface, by default SurfaceType.SENSITIVE
properties (SurfaceProperties, optional) – Reflectance/transmittance properties of the unsensitive surface where pixels lie, by default None.
material_in (material, optional) – Material of the space before the surface front side, i.e. the material in which photons arriving with a negative z-component of their direction vector are travelling. By default standard air.
material_out (material, optional) – Material of the space after the surface back side. I.e. the material in which photons arriving with a positive z-component of their direction vector are travelling, by default standard air.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`check_pixels_contained`()	Checks if all pixels are fully contained within the module outer aperture and fall completely outside the central hole (if any).
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`get_sensor_info`()	Returns the sensor info array for the ray tracing kernel.
`get_surface_normal_vector`(x, y)	Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.
`sagitta`(r)	Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

Attributes:

Treat the surface as a segment centered at these aperture coordinates.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

check_pixels_contained()

Checks if all pixels are fully contained within the module outer aperture and fall completely outside the central hole (if any).

This uses a conservative geometric check based on the bounding circle of each pixel.

Returns:: True if all pixels are validly placed, False otherwise.
Return type:: bool

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

get_sensor_info()

Returns the sensor info array for the ray tracing kernel. Automatically allocates and populates the PixelData and SurfaceOpticalTables arrays on the GPU.

Returns:: An array of shape (8,) and dtype float32 containing the packed sensor data.
Return type:: numpy.ndarray

get_surface_normal_vector(x, y)

Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.

Parameters:

x (float) – x coordinate of the point.
y (float) – y coordinate of the point.

Returns:

Normal unit vector.

Return type:

np.ndarray

offset: Treat the surface as a segment centered at these aperture coordinates.

sagitta(r)

Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.

Parameters:: r (np.ndarray, list or scalar) – Radial distance(s) from the optical axis.
Returns:: Sagitta value(s) at the given radial distance(s).
Return type:: np.ndarray

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.GenericPixel(x, y, half_size, shape, pixel_id, n_ucells_per_side=1, properties=None)

Represents a single pixel to be placed in a GenericFlatModule.

x

x-coordinate of the pixel in module coordinates.

Type:: float

y

y-coordinate of the pixel in module coordinates.

Type:: float

half_size

Half-size of the pixel (inradius, radius or half-side, depending on the shape).

Type:: float

shape

Shape of the pixel aperture.

Type:: ApertureShape

pixel_id

Unique identifier for the pixel.

Type:: int

n_ucells_per_side

Number of micro-cells per side of the pixel, by default 1.

Type:: int, optional

properties

Reflectance and/or efficiency of the pixel, by default None.

Type:: SurfaceProperties, optional

Warning

Micro-cell ID calculation do not take into account the shape of the pixel. Instead, if the pixel is not square, the ID is calculated relative to a square with half-side equal to the circumradius of the pixel. The effect of this approximation has not been tested.

Methods:

get_cuda_record()

Packs the pixel geometry into a structured NumPy array for CUDA kernels.

get_cuda_record()

Packs the pixel geometry into a structured NumPy array for CUDA kernels.

Return type:: void

class iactsim.optics.Materials

A collection of Material instances with refractive index data (wavelength in nm). Includes default materials: Air (Ciddor 1996) and Fused Silica (Malitson 1965).

New materials can be added using the register_material() method:

You can also replace a material, for example the air refractive index:

To register a refractive index for air, a set_atmospheric_conditions() method is provided. It uses the Ciddor equation following the NIST implementation:

Warning

Material integer IDs (.value) are assigned sequentially starting from 0, strictly based on the order in which they are registered. Because there is no mechanism to unregister a material, the sequence is guaranteed to be gapless. Overwriting an existing material (overwrite=True) safely preserves its original integer ID. This gapless sequence

Methods:

set_atmospheric_conditions([pressure, ...])

Calculate the refractive index of moist air using the Ciddor equation and update the default air material.

classmethod set_atmospheric_conditions(pressure=101325., temperature=20., co2_concentration=450., relative_humidity=0., lambda_min=200., lambda_max=1700.)

Calculate the refractive index of moist air using the Ciddor equation and update the default air material.

Follows the NIST implementation described by Jack A. Stone and Jay H. Zimmerman.

Parameters:

pressure (float) – Air pressure in Pascals.
temperature (float) – Air temperature in degrees Celsius.
co2_concentration (float) – CO2 concentration in micromoles per mole (µmol/mol), equivalent to ppm.
relative_humidity (Optional[float]) – Relative humidity in percent (%). If None, assumes dry air (xv = 0).
lambda_min (float, Optional[float]) – Minimum photon wavelength (in nm).
lambda_max (float, Optional[float]) – Maximum photon wavelength (in nm).

Return type:

Notes

NIST implementation is valid in the range 300 nm - 1700 nm.

class iactsim.optics.OpticalStackSimulator(core_materials, core_thicknesses, ambient='Air', substrate='SiO2', coh_list=[])

A class to handle dispersive Transfer Matrix Method (TMM) simulations using the tmm_fast backend, with a dynamic material database.

Parameters:

core_materials (List[str]) – List of material names for the core layers (from top to bottom).
core_thicknesses (List[float]) – List of thicknesses for the core layers in nanometers.
ambient (str, optional) – Name of the ambient medium (default is “Air”).
substrate (str, optional) – Name of the substrate material (default is “SiO2”).
coh_mask (list, optional) – List of coherence tags (‘c’ for coherent, ‘i’ for incoherent) for each layer (including ambient and substrate). If empty, coherent simulation is assumed.

Raises:

ImportError – If neither ‘tmm_fast’ nor ‘tmm’ package is installed.

Methods:

`get_available_materials`()	Returns a sorted list of all currently registered material names.
`get_refractive_index`(material, wavelengths_nm)	Get the refractive index of a registered material at specified wavelengths.
`plot_simulation_results`([mode, cmap, ...])	Plots simulation results for s-polarization, p-polarization, and unpolarized light.
`register_ciddor_air`([name, p, t, xCO2, rh])	Register the air refractive index using the Ciddor equation.
`register_material`(name, n_func)	Register a custom material using a refractive index function.
`register_sellmeier_material`(name, B_coeffs, ...)	Register a material defined by the Sellmeier equation.
`run`([polarization])	Run the TMM simulation for a specific polarization.
`set_simulation_params`([wl_range, angle_range])	Set the wavelength (in nanometers) and angle ranges (in degrees).

get_available_materials()

Returns a sorted list of all currently registered material names.

Return type:: List[str]

get_refractive_index(material, wavelengths_nm)

Get the refractive index of a registered material at specified wavelengths.

Parameters:

material (str) – The name of the material.
wavelengths_nm (np.ndarray or List[float] or float) – Wavelengths in nanometers.

Returns:

Complex refractive indices at the specified wavelengths.

Return type:

np.ndarray

plot_simulation_results(mode='R', cmap='Spectral', show_all_pol=True)

Plots simulation results for s-polarization, p-polarization, and unpolarized light. Automatically calculates axis extent from the stored simulation parameters.

Parameters:

mode (str) – ‘R’ for Reflectance or ‘T’ for Transmittance. Determines which data key to use.
cmap (str, optional) – The colormap to use for the plots.

Return type:

register_ciddor_air(name='Air', p=101325.0, t=288.15, xCO2=450.0, rh=0.0)

Parameters:

name (str) – The material name to register (defaults to “Air”, overwriting the default vacuum).
p (float) – Pressure in Pascals (default 101325 Pa).
t (float) – Temperature in Kelvin (default 288.15 K).
xCO2 (float) – CO2 concentration in ppm (default 450 ppm).
rh (float, optional) – Relative humidity (0.0 to 1.0).

Return type:

register_material(name, n_func)

Parameters:

name (str) – The name to refer to the material.
n_func (Callable) – Function accepting 1D wavelengths (m) and returning 1D complex indices.

Return type:

register_sellmeier_material(name, B_coeffs, C_coeffs)

Return type:: None

run(polarization='s')

Run the TMM simulation for a specific polarization.

Return type:: ndarray

set_simulation_params(wl_range=(200, 1000, 801), angle_range=(0, 90, 91))

Set the wavelength (in nanometers) and angle ranges (in degrees).

Parameters:

wl_range (Tuple, List, or np.ndarray) – If tuple: (start_nm, stop_nm, points). If array/list: exact wavelengths in Nanometers. Default is (200, 1000, 801).
angle_range (Tuple, List, or np.ndarray) – If tuple: (start_deg, stop_deg, points). If array/list: exact angles in Degrees. Default is (0, 90, 91).

Return type:

class iactsim.optics.OpticalSystem(surfaces, name=None)

Represents a generic optical system.

Parameters:

name (str, optional) – Name of the optical system, by defaults “OS”.
surfaces (List[Surface]) – List of Surface objects representing the optical surfaces in the system (the order is not important).

Notes

Each surface has a name attribute that is used for named access. If a surface name is None, a default name “Surface_i” (where i is its index) is assigned.

Methods:

`__getitem__`(key)	Allows accessing individual surfaces using indexing or by surface name.
`__iter__`()	Returns an iterator over the optical surfaces.
`__len__`()	Returns the number of optical surfaces in the system.
`__repr__`()	Returns a string representation of the optical system.
`add_surface`(surface[, replace])	Add a surface to the optical syste.
`remove_surface`(surface)	Remove a given surface.

Attributes:

surfaces_dict

Provides a dictionary view of the surfaces, mapping names to Surface objects.

__getitem__(key)

Allows accessing individual surfaces using indexing or by surface name.

Parameters:

key (str | int) – The name or index of the desired surface.

Returns:

The optical surface with the specified name or at the specified index.

Return type:

OpticalSurface

Raises:

KeyError – If a surface with the given name is not found.
IndexError – If the index is out of range.
TypeError – If the key is neither a string nor an integer.

__iter__()

Returns an iterator over the optical surfaces.

Returns:: An iterator object that iterates through the surfaces in self._surfaces.
Return type:: iterator

__len__()

Returns the number of optical surfaces in the system.

Returns:: The number of surfaces.
Return type:: int

__repr__()

Returns a string representation of the optical system.

Return type:: str

add_surface(surface, replace=False)

Add a surface to the optical syste.

Parameters:

surface (Surface) – Surface to be added.
replace (bool, optional) – Whether to replace an exisisting surface with the same name, by default False.

Raises:

ValueError – If the surface already exists and replace is False.

remove_surface(surface)

Remove a given surface.

Parameters:: surface (Surface or str) – Surface instance or name to be removed.

property surfaces_dict: Dict[str, AsphericalSurface]: Provides a dictionary view of the surfaces, mapping names to Surface objects.

class iactsim.optics.RefractiveIndexTexture(texture, wavelength_start, wavelength_inv_step, _cuda_array=None): Holds the texture object and metadata for refractive index lookups. It retains a reference to the underlying CUDA array to prevent premature garbage collection.

class iactsim.optics.SensorSurfaceType(*values)

Enumeration representing different types of sensor surfaces.

NONE

Represents no specific sensor surface type.

Type:: int

SIPM_TILE

Represents a SiPM tile sensor surface.

Type:: int

Methods:

`__contains__`(value)	Return True if value is in cls.
`__getitem__`(name)	Return the member matching name.
`__iter__`()	Return members in definition order.
`__len__`()	Return the number of members (no aliases)

classmethod __contains__(value)

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members.

classmethod __getitem__(name): Return the member matching name.

classmethod __iter__(): Return members in definition order.

classmethod __len__(): Return the number of members (no aliases)

class iactsim.optics.SipmStackSimulator(layers, thicknesses, medium, type_layers, depletion_layer_depth=5.0, depletion_layer_width=2100.0, fill_factor=1.0, breakdown_probability=1.0, ucell_size=75e-6)

A simulator for calculating the Photon Detection Efficiency (PDE) of Silicon Photomultipliers (SiPMs) given a coating stack.

This class extends OpticalStackSimulator to model the optical transport through thin-film coatings into a Silicon substrate. It calculates the PDE by combining optical transmittance with the probability of electron-hole pair generation within the active depletion region.

Parameters:

layers (list of str) – List of material names for the coating stack (e.g., ["Si3N4", "SiO2"]).
thicknesses (list of float) – List of layer thicknesses in meters.
medium (str) – The incident medium material name (e.g., "Air").
type_layers (list of str) – List of layer types corresponding to layers: - 'c': Coherent (phase-sensitive, interference calculated). - 'i': Incoherent (phase-averaged, intensity addition).
depletion_layer_depth (float, optional) – Depth of the start of the depletion region ($x_1$) in nm. Default is 5.0 nm.
depletion_layer_width (float, optional) – Depth extent of the depletion region ($x_2$) in nm. Default is 2100.0 nm.
fill_factor (float, optional) – Geometric fill factor ($FF$). Default is 1.0.
breakdown_probability (float, optional) – Avalanche triggering probability ($P_{br}$). Default is 1.0.
ucell_size (float, optional) – Size of the micro-cell in meters. Default is 75e-6 m.

Methods:

`constrain_pde`(lambda0, pde0)	Adjusts the breakdown probability to force the PDE to match a specific value at a specific wavelength (at normal incidence).
`get_available_materials`()	Returns a sorted list of all currently registered material names.
`get_refractive_index`(material, wavelengths_nm)	Get the refractive index of a registered material at specified wavelengths.
`get_surfcace_properties_obj`([...])	Creates a SurfaceProperties object from the simulation results.
`plot_pde_normal`([compare_data, compare_model])	Plots the simulated PDE at normal incidence against optional comparison data.
`plot_pde_results`([mode, cmap])	Plots simulation results for s-polarization, p-polarization, and unpolarized light.
`plot_simulation_results`([mode, cmap, ...])	Plots simulation results for s-polarization, p-polarization, and unpolarized light.
`register_ciddor_air`([name, p, t, xCO2, rh])	Register the air refractive index using the Ciddor equation.
`register_material`(name, n_func)	Register a custom material using a refractive index function.
`register_sellmeier_material`(name, B_coeffs, ...)	Register a material defined by the Sellmeier equation.
`run`([polarization])	Execute the simulation to calculate quantum efficiency and PDE.
`set_simulation_params`([wl_range, angle_range])	Set the wavelength (in nanometers) and angle ranges (in degrees).

constrain_pde(lambda0, pde0)

Adjusts the breakdown probability to force the PDE to match a specific value at a specific wavelength (at normal incidence).

This is useful for calibrating the model against a known experimental data point. It modifies self.breakdown_probability in place.

Parameters:

lambda0 (float) – The target wavelength in nanometers.
pde0 (float) – The target PDE value (0.0 to 1.0) at that wavelength.

Raises:

RuntimeError – If run() has not been called yet.

get_available_materials()

Returns a sorted list of all currently registered material names.

Return type:: List[str]

get_refractive_index(material, wavelengths_nm)

Get the refractive index of a registered material at specified wavelengths.

Parameters:

material (str) – The name of the material.
wavelengths_nm (np.ndarray or List[float] or float) – Wavelengths in nanometers.

Returns:

Complex refractive indices at the specified wavelengths.

Return type:

np.ndarray

get_surfcace_properties_obj(with_reflections=True, side='both')

Creates a SurfaceProperties object from the simulation results.

Parameters:

with_reflections (bool, optional) – If True, the surface properties will include the simulated reflectance and absorption. The detection efficiency will be defined relative to absorbed photons (‘absorbed’ kind). If False, reflectance is set to zero, and detection efficiency is defined relative to incident photons (‘incident’ kind). Default is True.
side (str, optional) – Specifies which side(s) of the surface to populate properties for. Options are ‘front’, ‘back’, or ‘both’. Default is ‘both’.

Returns:

The populated surface properties object containing wavelength, incidence angle, reflectance, absorption, and efficiency data.

Return type:

SurfaceProperties

plot_pde_normal(compare_data=None, compare_model=None)

Plots the simulated PDE at normal incidence against optional comparison data.

Parameters:

compare_data (tuple, optional) – Experimental data tuple (wavelengths, values, errors).
compare_model (tuple, optional) – External model data tuple (wavelengths, values).

Return type:

plot_pde_results(mode='R', cmap='Spectral')

Plots simulation results for s-polarization, p-polarization, and unpolarized light. Automatically calculates axis extent from the stored simulation parameters.

Parameters:

mode (str) – ‘R’ for Reflectance or ‘T’ for Transmittance. Determines which data key to use.
cmap (str, optional) – The colormap to use for the plots.

Return type:

plot_simulation_results(mode='R', cmap='Spectral', show_all_pol=True)

Plots simulation results for s-polarization, p-polarization, and unpolarized light. Automatically calculates axis extent from the stored simulation parameters.

Parameters:

mode (str) – ‘R’ for Reflectance or ‘T’ for Transmittance. Determines which data key to use.
cmap (str, optional) – The colormap to use for the plots.

Return type:

register_ciddor_air(name='Air', p=101325.0, t=288.15, xCO2=450.0, rh=0.0)

Parameters:

name (str) – The material name to register (defaults to “Air”, overwriting the default vacuum).
p (float) – Pressure in Pascals (default 101325 Pa).
t (float) – Temperature in Kelvin (default 288.15 K).
xCO2 (float) – CO2 concentration in ppm (default 450 ppm).
rh (float, optional) – Relative humidity (0.0 to 1.0).

Return type:

register_material(name, n_func)

Parameters:

name (str) – The name to refer to the material.
n_func (Callable) – Function accepting 1D wavelengths (m) and returning 1D complex indices.

Return type:

register_sellmeier_material(name, B_coeffs, C_coeffs)

Return type:: None

run(polarization='unpolarized')

Execute the simulation to calculate quantum efficiency and PDE.

The method performs the following steps: 1. Calculate optical transmittance into the Silicon substrate. 2. Calculate the internal path lengths correcting for refraction/incidence angle. 3. Computes the Silicon absorption coefficient from the complex refractive index. 4. Computes the probability of photon absorption strictly within the depletion region. 5. Combines factors: $PDE = T times P_{int} times FF times P_{br}$.

Parameters:: polarization (str, optional) – Polarization mode: 's', 'p', or 'unpolarized' (default). If 'unpolarized', the average of s and p transmittances is used.
Returns:: The calculated PDE array with shape (n_angles, n_wavelengths).
Return type:: np.ndarray

set_simulation_params(wl_range=(200, 1000, 801), angle_range=(0, 90, 91))

Set the wavelength (in nanometers) and angle ranges (in degrees).

Parameters:

wl_range (Tuple, List, or np.ndarray) – If tuple: (start_nm, stop_nm, points). If array/list: exact wavelengths in Nanometers. Default is (200, 1000, 801).
angle_range (Tuple, List, or np.ndarray) – If tuple: (start_deg, stop_deg, points). If array/list: exact angles in Degrees. Default is (0, 90, 91).

Return type:

class iactsim.optics.SipmTileSurface(pixels_per_side, pixel_active_side, pixels_separation, border_to_active_area, sensor_id, first_pixel_id, microcell_size=0.0, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), scattering_dispersion=0.0, surface_type=SurfaceType.SENSITIVE, properties=None, material_in=Materials.AIR, material_out=Materials.AIR, name=None)

Represents a SiPM tile of NxN pixels.

Parameters:

pixels_per_side (int) – Number of pixels per side.
pixel_active_side (float) – Side length of the active area of a single pixel.
pixels_separation (float) – Separation between pixels.
border_to_active_area (float) – Width of the border from the edge of the tile to the active area.
sensor_id (int) – Unique identifier for the sensor.
first_pixel_id (int) – ID of the first pixel in the tile.
microcell_size (float, optional) – Size of a pixel micro-cell in mm (e.g. 0.075 for 75um ucells), by default 0.0 (i.e. not considered).
position (array-like, optional) – Position of the surface center [x, y, z], by default None
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
scattering_dispersion (float, optional) – Standard deviation of Gaussian scattering after reflection/transmission, by default 0.0
properties (SurfaceProperties, optional) – Reflectance/transmittance properties of the surface, by default None
material_in (material, optional) – Material of the space before the surface front side. I.e. the material in which photons arriving with a negative z-component of their direction vector are travelling, by default standard air.
material_out (material, optional) – Material of the space after the surface back side. I.e. the material in which photons arriving with a positive z-component of their direction vector are travelling, by default standard air.
name (str, optional) – Surface name

Notes

Tile layout:

  y       pixels_separation
  ^    ________ <--> ________
  |   |        |    |        |
  |   |        |    |        |
  |   |        |    |        |
  |   |________|    |________|
  |<->               <------>
  | |            pixel_active_side
  | border_to_active_area
(0,0)---------> x

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`get_surface_normal_vector`(x, y)	Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.
`sagitta`(r)	Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

Attributes:

Treat the surface as a segment centered at these aperture coordinates.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

get_surface_normal_vector(x, y)

Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.

Parameters:

x (float) – x coordinate of the point.
y (float) – y coordinate of the point.

Returns:

Normal unit vector.

Return type:

np.ndarray

offset: Treat the surface as a segment centered at these aperture coordinates.

sagitta(r)

Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.

Parameters:: r (np.ndarray, list or scalar) – Radial distance(s) from the optical axis.
Returns:: Sagitta value(s) at the given radial distance(s).
Return type:: np.ndarray

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.SphericalSurface(half_aperture, curvature, central_hole_half_aperture=0., aperture_shape=ApertureShape.CIRCULAR, central_hole_shape=ApertureShape.CIRCULAR, is_fresnel=False, surface_type=SurfaceType.REFLECTIVE, position=np.array([0., 0., 0.]), tilt_angles=np.array([0., 0., 0.]), scattering_dispersion=0., properties=None, material_in=Materials.AIR, material_out=Materials.AIR, name=None)

Represents a spherical optical surface.

Parameters:

half_aperture (float) – Half-aperture of the surface.
curvature (float) – Surface curvature (1/radius of curvature)
central_hole_half_aperture (float, optional) – Half-aperture of the central hole (0.0 if no hole), by default 0.0
aperture_shape (ApertureShape, optional) – Shape of the aperture (circular, hexagonal or rectangular), by default ApertureShape.CIRCULAR
central_hole_shape (ApertureShape, optional) – Shape of the central hole (circular, hexagonal or rectangular), by default ApertureShape.CIRCULAR
is_fresnel (bool, optional) – Whether the surface is an ideal Fresnel lens/mirror, by default False
surface_type (SurfaceType, optional) – Type of surface (reflective, refractive, opaque, dummy), by default SurfaceType.REFLECTIVE
position (array-like, optional) – Position of the surface center [x, y, z], by default None
tilt_angles (array-like, optional) – Tilt angles (counter-clockwise x-tilt, y-tilt and z_tilt) in degrees, by default no tilt.
scattering_dispersion (float, optional) – Standard deviation of Gaussian scattering after reflection/transmission, by default 0.
properties (SurfaceProperties, optional) – Reflectance/transmittance properties of the surface, by default None
material_in (material, optional) – Material of the space before the surface front side. I.e. the material in which photons arriving with a negative z-component of their direction vector are travelling, by default standard air.
material_out (material, optional) – Material of the space after the surface back side. I.e. the material in which photons arriving with a positive z-component of their direction vector are travelling, by default standard air.
name (str, optional) – Surface name

Methods:

`__repr__`()	Returns a string representation of the surface object.
`__str__`()	Returns a string representation of the surface object formatted as a table.
`get_cuda_record`()	Returns the surface properties packed into a structured NumPy record.
`get_rotation_matrix`()	Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.
`get_surface_normal_vector`(x, y)	Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.
`sagitta`(r)	Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.
`set_rotation_matrix`(a_matrix)	Set a custom rotation matrix instead of deriving it from tilt angles.

Attributes:

Treat the surface as a segment centered at these aperture coordinates.

__repr__()

Returns a string representation of the surface object.

Return type:: str

__str__()

Returns a string representation of the surface object formatted as a table.

Return type:: str

get_cuda_record()

Returns the surface properties packed into a structured NumPy record.

Return type:: void

get_rotation_matrix()

Calculates the 3D rotation matrix to transform into the surface reference system from the telescope reference system.

Tilt angles are expected in degrees.

Return type:: ndarray
Returns:: np.ndarray: A 3x3 rotation matrix. The returned matrix is the transpose of the tilt sequence. It transforms from the telescope reference system into the surface reference system.

get_surface_normal_vector(x, y)

Calculate the upward-going normal unit vector at a given surface point (x,y) in the surface reference frame.

Parameters:

x (float) – x coordinate of the point.
y (float) – y coordinate of the point.

Returns:

Normal unit vector.

Return type:

np.ndarray

offset: Treat the surface as a segment centered at these aperture coordinates.

sagitta(r)

Calculate the sagitta of the aspheric surface at a given radial distance in the surface refrence frame.

Parameters:: r (np.ndarray, list or scalar) – Radial distance(s) from the optical axis.
Returns:: Sagitta value(s) at the given radial distance(s).
Return type:: np.ndarray

set_rotation_matrix(a_matrix)

Set a custom rotation matrix instead of deriving it from tilt angles. To use tilt angles set it to None.

Parameters:: a_matrix (np.ndarray) – 3D rotation matrix to transform from telescope to surface reference frame.

class iactsim.optics.SurfaceProperties(transmittance=None, reflectance=None, absorption=None, transmittance_back=None, reflectance_back=None, absorption_back=None, wavelength=None, incidence_angle=None, efficiency=None, efficiency_kind='incident', efficiency_wavelength=None, efficiency_incidence_angle=None)

Represents surface transmittance, reflectance, absorption and detection efficiency as a function of photon wavelength and incidence angle.

Attributes:

efficiency_kind

'incident' (relative to incoming photons) or 'absorbed' (relative to absorbed photons).

Methods:

`get_cuda_record`()	Packs the texture pointers and grid metadata into a structured NumPy array for CUDA kernels.
`get_textures`()	Creates and caches a SurfaceTextures object.
`load_json`(filename)	Loads surface attributes from a JSON file.
`plot`([kind, heatmap, cmap, level_range])	Plot properties including transmittance, reflectance, absorption, and efficiency.
`save_json`(filename)	Saves the raw surface attributes to a JSON file.

efficiency_kind: str = 'incident': ‘incident’ (relative to incoming photons) or ‘absorbed’ (relative to absorbed photons).

get_cuda_record()

Packs the texture pointers and grid metadata into a structured NumPy array for CUDA kernels.

Return type:: void

get_textures()

Creates and caches a SurfaceTextures object. If properties haven’t changed, returns the cached version.

Return type:: SurfaceTextures

classmethod load_json(filename): Loads surface attributes from a JSON file.

plot(kind='transmittance', heatmap=None, cmap='Spectral', level_range=(None, None)): Plot properties including transmittance, reflectance, absorption, and efficiency.

save_json(filename): Saves the raw surface attributes to a JSON file.

class iactsim.optics.SurfaceShape(*values)

Enumeration representing different types of surface shapes.

This enum defines common surface shapes encountered in optical systems or other fields requiring precise geometrical definitions.

Attributes:

`ASPHERICAL`	Represents an aspherical surface.
`BOX`	Represents a box-like surface.
`CONICAL`	Represents a conical surface.
`CYLINDRICAL`	Represents a cylindrical surface.
`FLAT`	Represents a flat surface.
`SPHERICAL`	Represents a spherical surface.

Methods:

`__contains__`(value)	Return True if value is in cls.
`__getitem__`(name)	Return the member matching name.
`__iter__`()	Return members in definition order.
`__len__`()	Return the number of members (no aliases)

ASPHERICAL = 0: Represents an aspherical surface.

BOX = 5: Represents a box-like surface.

CONICAL = 4: Represents a conical surface.

CYLINDRICAL = 1: Represents a cylindrical surface.

FLAT = 2: Represents a flat surface.

SPHERICAL = 3: Represents a spherical surface.

classmethod __contains__(value)

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members.

classmethod __getitem__(name): Return the member matching name.

classmethod __iter__(): Return members in definition order.

classmethod __len__(): Return the number of members (no aliases)

class iactsim.optics.SurfaceTextures(transmittance, reflectance, transmittance_back, reflectance_back, optical_wavelength_start, optical_wavelength_inv_step, optical_angle_start, optical_angle_inv_step, efficiency, efficiency_wavelength_start, efficiency_wavelength_inv_step, efficiency_angle_start, efficiency_angle_inv_step, _t_array=None, _r_array=None, _t_back_array=None, _r_back_array=None, _eff_array=None)

Container for GPU texture objects (optical + efficiency) and the metadata required to map physical values (wavelength, angle) to texture coordinates. It can retains a reference to the underlying CUDA arrays to prevent premature garbage collection. Because efficiency can be defined on a different grid than transmittance/reflectance, this class stores two separate sets of coordinate mappings.

Methods:

get_cuda_record()

Packs the texture pointers and grid metadata into a structured NumPy array for CUDA.

get_cuda_record()

Packs the texture pointers and grid metadata into a structured NumPy array for CUDA.

Return type:: void

class iactsim.optics.SurfaceType(*values)

Enumeration representing the different types of optical surfaces.

The directionality of reflection and sensitivity (e.g., “from above” or “from below”) is defined within the local reference frame of the surface at the point of photon incidence. As a reference:

the front side of a surface with negative curvature is the convex side.

the front side of a surface with posistive curvature is the concave side.

REFLECTIVE

Represents a reflective surface (both sides).

Type:: int

REFLECTIVE_FRONT

Represents a surface that is reflective on the front side. In the surface reference frame, only photons arriving with a negative z-component of their direction vector are reflected. The curvature of the surface does not affect this behavior.

Type:: int

REFLECTIVE_BACK

Represents a surface that is reflective on the back side. In the surface reference frame, only photons arriving with a positive z-component of their direction vector are reflected. The curvature of the surface does not affect this behavior.

Type:: int

REFRACTIVE

Represents a refractive surface. The refraction is the same on both sides.

Type:: int

SENSITIVE

Represents the focal plane surface where photons are detected. The sensitivity is the same on both sides.

Type:: int

SENSITIVE_BACK

Represents a surface that is sensitive on the front side. In the surface reference frame, only photons arriving with a negative z-component of their direction vector are detected. The curvature of the surface does not affect this behavior.

Type:: int

SENSITIVE_FRONT

Represents a surface that is sensitive on the back side. In the surface reference frame, only photons arriving with a positive z-component of their direction vector are detected. The curvature of the surface does not affect this behavior.

Type:: int

OPAQUE

Represents a surface that blocks light.

Type:: int

DUMMY

Represents a surface that neither reflects nor refracts light. It can be used to introduce artificial absorption or scattering effects, serving as a means to model specific behaviors within the optical system.

Type:: int

Methods:

`__contains__`(value)	Return True if value is in cls.
`__getitem__`(name)	Return the member matching name.
`__iter__`()	Return members in definition order.
`__len__`()	Return the number of members (no aliases)

classmethod __contains__(value)

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members.

classmethod __getitem__(name): Return the member matching name.

classmethod __iter__(): Return members in definition order.

classmethod __len__(): Return the number of members (no aliases)

class iactsim.optics.SurfaceVisualProperties(color=None, opacity=None, specular=None, wireframe=False, resolution=None, visible=True)

Stores visualization attributes for an optical surface.

Parameters:

color (tuple of float, optional) – RGB color tuple (0.0-1.0). If None, the visualizer uses default logic based on surface type.
opacity (float, optional) – Opacity (0.0 transparent - 1.0 opaque). If None, visualizer uses default logic based on surface type.
specular (float, optional) – Specular reflection intensity (0.0-1.0).
wireframe (bool, optional) – If True, forces wireframe representation for this surface. Default is False.
resolution (float, optional) – Mesh resolution in mm. If None, uses the visualizer logic based on the surface extent.
visible (bool, optional) – Whether the surface is visible in the render. Default is True.

optics.ray_tracing

Functions:

`atmospheric_transmission`	Simulates atmospheric transmission.
`generate_bunch_wavelengths`	Generates wavelengths for bunches using the Cherenkov emission spectrum.
`ray_tracing`	The main ray tracing kernel.
`reject_by_weight`	Applies rejection to photons based on their fractional weights.
`shift_bunches_position`	Shift bunches from the current plane (the telescope plane in the case of CORSIKA files) to a plane at a level target_z
`unpack_bunches`	Unpacks photon bunches into individual photons and generates unique wavelengths following the Cherenkov emission spectrum.

iactsim.optics.ray_tracing.atmospheric_transmission()

Simulates atmospheric transmission.

This kernel function applies atmospheric transmission rejecting photons based on a 2D transmission curve (wavelength and emission altitude). Physically, it models the attenuation of light due to scattering (Rayleigh/Mie) and molecular absorption (like ozone) by evaluating the Beer-Lambert law.

Parameters:

ps (float3*) – Array of photon positions.
vs (float3*) – Array of photon directions. The z-component scales the path length the photon takes through the atmosphere.
wls (float*) – Array of photon wavelengths.
ts (float*) – Array of photon times.
zems (const float*) – Array of photon emission altitudes.
tr_curves (const float*) – Array containing the 2D transmission curve data, i.e. a lookup table of vertical optical depths (tau).
tr_curve_wl (const float*) – Array of wavelength values for the transmission curve.
tr_curve_zem (const float*) – Array of emission altitude values for the transmission curve.
tr_curve_sizes (const int*) – Array containing the dimensions (x1_size, x2_size) of the 2D transmission curve. tr_curve_sizes[0] is the wavelength size, and tr_curve_sizes[1] is the emission altitude size.
n_ph (int) – The total number of photons.
seed (unsigned long long) – Random seed to initialize the RNG.
use_log_z (bool) – If true, the emission altitude interpolation uses logarithmic weighting.

Notes

Input array usage: - used to compute transmission: wls, zems, vs, tr_curves, tr_curve_wl, tr_curve_zem, and tr_curve_sizes. - used only to reject photons: ps and ts (These, along with vs and wls, are passed to the rejection function to update photon state).

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.ray_tracing.generate_bunch_wavelengths()

Generates wavelengths for bunches using the Cherenkov emission spectrum.

Parameters:

wls (float*) – Pointer to the array of photon wavelengths.
n_bunches (int) – Total number of bunches.
inv_l_min (float) – Inverse of the minimum wavelength boundary.
inv_l_max (float) – Inverse of the maximum wavelength boundary.
seed (unsigned long long) – Random seed for curand.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.ray_tracing.ray_tracing()

The main ray tracing kernel.

This kernel traces individual photons through an optical system, simulating their interactions with surfaces. Surface properties are consolidated into an array of SurfaceData structures.

Interpretation of SurfaceData members depends on surface type:

Aperture Size (SurfaceData.aperture_size):

For aspherical, spherical and flat surfaces: half-aperture of the surface (aperture_size.x) and half-aperture of the central hole (aperture_size.y). The interpretation depends on the outer and inner shape: the radius for “circular”, inradius for “hexagonal” and half-side for “square”.

For a cylindrical surface they represent radius (aperture_size.x) and height (aperture_size.y).

Flags (SurfaceData.flags):

For aspherical and spherical surfaces: flags[0] indicates if a surface is a Fresnel surface (i.e. is flat, but has the same normal of a non-flat surface).

For cylindrical surfaces: flags[0] indicates if the surface has a top flat surface; flags[1] indicates if the surface has a bottom flat surface. If both are true the surface is a solid cylinder.

Parameters:

ps (float3*) – Array of photon positions (x, y, z).
vs (float3*) – Array of photon directions (normalized vectors, x, y, z).
wls (float*) – Array of photon wavelengths.
times (float*) – Array of photon times (time elapsed since the start of the trace).
pixel_ids (int*) – ID of the pixel reached by the photon.
sub_pixel_ids (int*) – ID of the sub-pixel reached by the photon.
surface_ids (int*) – ID of the surface (stores the surface ID if save_last_bounce is true, otherwise 0).
telescope_position (const float3*) – Position of the telescope (global system).
telescope_rotation_matrix (const float*) – Rotation matrix of the telescope (global system).
surfaces (const SurfaceData*) – Array of SurfaceData structures containing geometry and physical properties for each surface.
optical_tables (const SurfaceOpticalTables*) – Structure containing texture objects and scaling factors for surface transmittance/reflectance.
refractive_tables (const RefractiveIndexTable*) – Array of RefractiveIndexTable structures (one per material) for refractive index lookups.
num_surfaces (int) – The total number of surfaces in the optical system.
num_photons (int) – The total number of photons to trace.
max_bounces (int) – Maximum number of interactions allowed per photon.
save_last_bounce (bool) – If true, stores the position of the last bounce (updates surface_ids).
trans_det_back_to_telescope (bool) – Whether to move detected photons into the telescope reference system.
seed (unsigned long long) – Random number generator seed.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.ray_tracing.reject_by_weight()

Applies rejection to photons based on their fractional weights.

@param[in,out] ps Pointer to the array of photon positions @param[in,out] vs Pointer to the array of photon directions @param[in,out] wls Pointer to the array of photon wavelengths @param[in,out] ts Pointer to the array of photon arrival times @param[in] weights Pointer to the array of fractional weights [0., 1.] for each photon @param[in] n Total number of photons to process @param[in] seed Base random seed to initialize the cuRAND state

This kernel evaluates the survival probability of each photon given a fractional photon weight (between 0. and 1.). It generates a uniform random number for each thread; if the random number exceeds the photon weight, the photon is discarded using the reject_photon device function (which sets its position, direction, time, and wavelength to NaN).

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.ray_tracing.shift_bunches_position()

Shift bunches from the current plane (the telescope plane in the case of CORSIKA files) to a plane at a level target_z

and update their time using the refractive index provided.

Parameters:

ps (float3*) – Pointer to the array of bunch positions.
vs (float3*) – Pointer to the array of bunch directions.
times (float*) – Pointer to the array of bunch arrival times.
wls (const float*) – Pointer to the array of bunch wavelengths.
target_z (float) – The target Z distance.
air_ri_table (Unknown) – RefractiveIndexTable struct for air to calculate light speed.
n_bunches (int) – Total number of bunches.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.ray_tracing.unpack_bunches()

Unpacks photon bunches into individual photons and generates unique wavelengths following the Cherenkov emission spectrum.

@param[in] in_pos Pointer to the input array of bunch positions @param[in] in_dir Pointer to the input array of bunch directions @param[in] in_time Pointer to the input array of bunch arrival times @param[in] in_alt Pointer to the input array of bunch emission altitudes @param[in] in_weight Pointer to the input array of bunch weights @param[out] out_pos Pointer to the output array of unpacked photon positions @param[out] out_dir Pointer to the output array of unpacked photon directions @param[out] out_time Pointer to the output array of unpacked photon arrival times @param[out] out_alt Pointer to the output array of unpacked photon emission altitudes @param[out] out_wl Pointer to the output array of generated photon wavelengths @param[out] out_weight Pointer to the output array of unpacked photon weights @param[in] bunch_size The number of individual photons contained in each single bunch @param[in] inv_l_min Inverse of the minimum wavelength boundary @param[in] inv_l_max Inverse of the maximum wavelength boundary @param[in] N_out Total number of output photons (number of input bunches times bunch size) @param[in] has_alt Boolean flag indicating whether emission altitudes should be copied @param[in] has_weight Boolean flag indicating whether fractional weights should be distributed @param[in] seed Random seed

This CUDA kernel expands arrays of photon “bunches” into individual photons. If a bunch contains bunch_size photons, its physical properties (position, direction, time, and optionally emission altitude) are duplicated bunch_size times in the output arrays. Simultaneously, a unique wavelength is assigned to each unpacked photon by sampling the Cherenkov emission spectrum, in the provided range, using a pre-generated uniformly distributed random number. If has_weight is true, the original bunch fractional weight is distributed across its unpacked constituent photons. For a bunch size of $N$ and a weight $W$ (where $W le N$), the first $lfloor W rfloor$ photons are assigned a weight of 1. The next photon receives the fractional remainder ($W - lfloor W rfloor$). Any subsequent photons in the bunch receive a weight of 0.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

optics.transforms

Functions:

`create_surface_rotation`(normal[, up])	Computes a rotation matrix to transform from the telescope reference frame to the surface reference frame.
`local_to_photon_rotation`(u)	Compute the rotation matrix to transform vector u to the local vertical Z-axis (0,0,1).
`local_to_pointing_rotation`(altitude, azimuth)	Compute the rotation matrix to transform from the local reference frame (North-West-Up) to the "pointing reference frame".
`local_to_telescope_rotation`(altitude, azimuth)	Compute the rotation matrix to transform from the local reference frame (North-West-Up) to the "telescope reference frame".
`local_to_telescope_transform`	Transforms photon positions and directions based on a telescope position and orientation.
`pointing_dir`(altitude, azimuth)	Telescope pointing direction in the corsika-like local reference frame.

iactsim.optics.transforms.create_surface_rotation(normal, up=np.array([1, 0, 0]))

Computes a rotation matrix to transform from the telescope reference frame to the surface reference frame.

In the surface reference system:

the Z-axis (0, 0, 1) is aligned with the input normal;
the Y-axis (0, 1, 0) is aligned as close as possible to the input up vector;
the X-axis (1, 0, 0) is mutually orthogonal.

Parameters:

normal (np.ndarray) – The vector in the telescope reference system that defines where the surface is facing. This will become the surface Z-axis.
up (np.ndarray, optional) – The vector in the telescope reference system that defines the “top” of the surface. The surface Y-axis will be constructed by projecting this vector onto the plane perpendicular to the normal. Defaults to the X axis of telescope reference frame ([1, 0, 0]).

Returns:

R – The 3x3 rotation matrix.

Usage:
- v_surf = R @ v_telescope if v_telescope has shape (3,)
- v_surf = v_telescope @ R.T if v_telescope has shape (N,3)

Return type:

ndarray, shape (3, 3)

Notes

The ID of each pixel of a SiPM tile is defined in the tile reference system as follows:

^ y
|     _____   _____   _____
|    |     | |     | |     |
|    |  6  | |  7  | |  8  |
|    |_____| |_____| |_____|
|     _____   _____   _____
|    |     | |     | |     |
|    |  3  | |  4  | |  5  |
|    |_____| |_____| |_____|
|     _____   _____   _____
|    |     | |     | |     |
|    |  0  | |  1  | |  2  |
|    |_____| |_____| |_____|
|
------------------------------> x

So, the SiPM tile rotation matrix must be carefully set to match the desired ID convention.

Examples

# Opposite to the pointing direction
sensor_normal = np.array([0., 0., -1.])

# Align the surface y axis with the telescope y axis
R = create_surface_rotation(normal=sensor_normal, up=np.array([0., 1., 0.]))

iactsim.optics.transforms.local_to_photon_rotation(u)

Compute the rotation matrix to transform vector u to the local vertical Z-axis (0,0,1).

This uses the Rodrigues rotation formula.

Parameters:: u (ndarray, shape (3,)) – The source unit vector (e.g., photon direction).
Returns:: R – Rotation matrix such that R @ u = [0, 0, 1].
Return type:: ndarray, shape (3, 3)

iactsim.optics.transforms.local_to_pointing_rotation(altitude, azimuth)

Compute the rotation matrix to transform from the local reference frame (North-West-Up) to the “pointing reference frame”.

This reference frame is defined such that when the telescope is pointing at the horizon towards the North (i.e. alt: 0, az: 0), the axes are aligned as follows:

z-axis: aligned with the telescope optical axis, pointing North.
x-axis: perpendicular to the optical axis, pointing downward.
y-axis: perpendicular to the optical axis, pointing west.

Parameters:

altitude (float) – Altitude angle of the telescope pointing, in degrees.
azimuth (float) – Azimuth angle of the telescope pointing, in degrees. Measured from North, increasing towards East.

Returns:

R – Rotation matrix. When a vector in the local reference frame is multiplied by this matrix it is transformed into the telescope reference frame.

Return type:

ndarray, shape (3, 3)

Notes

This is a simple rotation of the CORSIKA reference frame that move the up-vector (z) into the telescope direction.

iactsim.optics.transforms.local_to_telescope_rotation(altitude, azimuth, custom_rotation=None)

Compute the rotation matrix to transform from the local reference frame (North-West-Up) to the “telescope reference frame”. By deault the telescope refrence frame is the pointing reference frame (see local_to_pointing_rotation()).

Parameters:

altitude (float) – Altitude angle of the telescope pointing, in degrees.
azimuth (float) – Azimuth angle of the telescope pointing, in degrees. Measured from North, increasing towards East.

Returns:

R – Rotation matrix. When a vector in the local reference frame is multiplied by this matrix it is transformed into the telescope reference frame.

Return type:

ndarray, shape (3, 3)

Examples

To rotate the telescope frame around the optical axis (Z-axis), while keeping Z pointing in the same direction:

import numpy as np

# Rotation around Z-axis
rotation = np.array([
    [ 0, 1, 0], # new X is old Y
    [ 1, 0, 0], # new Y is old X
    [ 0, 0, 1]
])

# Get the telescope transformation matrix
R_tel = local_to_telescope_rotation(
    altitude=70,
    azimuth=180,
    custom_rotation=rotation
)

Now when the telescope is pointing North:

z-axis: aligned with the telescope optical axis, pointing North;
y-axis: perpendicular to the optical axis, pointing downward;
x-axis: perpendicular to the optical axis, pointing west.

iactsim.optics.transforms.local_to_telescope_transform()

Transforms photon positions and directions based on a telescope position and orientation.

This kernel performs a coordinate transformation on a set of photons, effectively simulating the observation of those photons by a telescope located at a specific position and with a specific orientation. The transformation consists of a translation and a rotation. Is assumed that the altitude axis is not displaced with respect to the azimuth axis and intersect at the telescope origin.

Parameters:

ps (float3*) – An array of float3 representing the positions of the photons. Modified in-place.
vs (float3*) – An array of float3 representing the direction vectors of the photons. Modified in-place.
p0 (float3) – A float3 representing the position of the telescope.
r_mat (float*) – A float array representing the rotation matrix.
n_ph (int) – The number of photons to transform.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.optics.transforms.pointing_dir(altitude, azimuth)

Telescope pointing direction in the corsika-like local reference frame.

North -> (0, 0) : x-axis
East -> (0, 90)
South -> (0, 180)
West -> (0, 270) : y-axis
Zenith -> (90, any) : z-axis

Parameters:

altitude (float) – Altitude angle in degrees.
azimuth (float) – Azimuth angle in degrees. Measured from North, increasing towards East (clockwise).

Returns:

direction – Pointing unit vector in the local reference frame (North-East-Up).

Return type:

ndarray, shape (3,)

optics.sources

Classes:

`Source`([telescope, dtype])	Represents a photon source.
`Spectrum`(dist_type)	Generate a photon spectral distribution.
`TimeDistribution`(dist_type)	Generate photon arrival times.

class iactsim.optics.sources.Source(telescope=None, dtype=np.float32)

Represents a photon source. By default a point-like source at zenith is generated. Photons are generated at a point (0, 0, 100) m in the local reference frame.

Parameters:

telescope (IACT | None, optional) – The IACT object associated with this source. If None, the source is assumed to be at a fixed position defined by self.positions.position. Otherwise, a point-like source is generated as a uniform disk, at a coordinates (0, 0, 100) m in the local reference frame, with a radius big enough to illimunate the aperture of the telescope.
dtype (type, optional) – The desired data type for generated quantities, by default np.float32.

Attributes:

`arrival_times`	Photon arrival times generator.
`directions`	Photon directions generator.
`positions`	Photon positions generator.
`spectrum`	Photon wavelengths generator.

Methods:

`generate`(n)	Generate n photons.
`set_target`([target, distance, target_reference])	Adjust source position to match the center of a target.
`visualize`([n_photons, opacity, length, ...])	VTK visualization of the source.

arrival_times: TimeDistribution: Photon arrival times generator.

directions: AbstractPhotonDirections: Photon directions generator.

generate(n)

Generate n photons.

Parameters:: n (int) – Number of photons to generate.
Returns:: ps, vs, wls, ts – Position, direction, wavelength and arrival time of photons.
Return type:: tuple of ndarrays

positions: AbstractPhotonPositions: Photon positions generator.

set_target(target=None, distance=1e5, target_reference='telescope')

Adjust source position to match the center of a target. If the target is not specified, it defaults to the telescope.

Parameters:

target (int, str, tuple, list, or ndarray, optional) – Name or index of the surface in the telescope optical system, or a specific (x, y, z) coordinate. By default None (telescope position).
distance (float) – Source-target distance in mm.
target_reference (str, optional) – Reference system of the specified target position if a coordinate is provided. Options are ‘telescope’ (default) or ‘global/local’.

spectrum: Spectrum: Photon wavelengths generator.

visualize(n_photons=1000, opacity=None, length=None, show_hits=True, show_rays=True, resolution=None)

VTK visualization of the source.

Parameters:

n_photons (int, optional) – Number of photons to generate, by default 1000.
opacity (float, optional) – Ray opacity, by default None (auto).
length (float, optional) – If provided, rays that not intersects the telescope will be drawn with this length using the direction vector.
show_hits (bool, optional) – Whether to show hits, by default True.
show_rays (bool, optional) – Whether to show rays, by default True.
resolution (float, optional) – Objects mesh resolution (in mm). By default None (depends on object extent).

Raises:

RuntimeError – If the source is not linked to a telescope.

class iactsim.optics.sources.Spectrum(dist_type)

Generate a photon spectral distribution.

Parameters:: dist_type (str) – Distribution type. Supported values are: “uniform”, “constant”, and “cherenkov”.

Attributes:

`dtype`	Data type for generated wavelengths.
`l0`	Central wavelength (in nm, used only if `type` is "constant").
`lmax`	Maximum wavelength (in nm).
`lmin`	Minimum wavelength (in nm).
`type`	"uniform", "constant" and "cherenkov".

Methods:

Generates wavelength samples based on the specified distribution.

dtype: type: Data type for generated wavelengths.

generate(n)

Generates wavelength samples based on the specified distribution.

Parameters:: n (int) – The number of samples to generate.
Returns:: sample – An array of generated wavelength samples.
Return type:: ndarray
Raises:: NotImplementedError – If the distribution type is not recognized.

l0: float: Central wavelength (in nm, used only if type is “constant”).

lmax: float: Maximum wavelength (in nm).

lmin: float: Minimum wavelength (in nm).

property type: str

“uniform”, “constant” and “cherenkov”.

Type:: Distribution type, supported values are

class iactsim.optics.sources.TimeDistribution(dist_type)

Generate photon arrival times.

Parameters:: dist_type (str) – Distribution type. Supported values are: “uniform” (i.e. Poissonian) and “constant”.

Attributes:

`dtype`	Data type for generated times.
`t0`	Central time (in ns, used only if `type` is "constant").
`tmax`	End time (in ns).
`tmin`	Start time (in ns).
`type`	"uniform" and "constant".

Methods:

Generates time samples based on the specified distribution.

dtype: type: Data type for generated times.

generate(n)

Generates time samples based on the specified distribution.

Parameters:: n (int) – The number of samples to generate.
Returns:: sample – An array of generated time samples.
Return type:: ndarray
Raises:: NotImplementedError – If the distribution type is not recognized.

t0: float: Central time (in ns, used only if type is “constant”).

tmax: float: End time (in ns).

tmin: float: Start time (in ns).

property type: str

“uniform” and “constant”.

Type:: Distribution type, supported values are

Classes:

`AbstractPhotonPositions`(position[, ...])	Abstract base class for a photon position generator.
`PointLike`(position[, rotation, dtype, seed])	Represents a point source by generating a set of identical 3D points.
`UniformDisk`(r_min, r_max[, position, ...])	Generates uniformly distributed points on a disk (or annulus) parallel to the x-y plane.
`UniformSphericalCap`(radius, angular_extent)	Generates uniformly distributed points on a spherical cap.

class iactsim.optics.sources.positions.AbstractPhotonPositions(position, rotation=None, dtype=cp.float32, seed=None)

Abstract base class for a photon position generator.

This class defines the interface for generating photon positions in 3D space.

position

The (x, y, z) coordinates of the point or center of the photon source.

Type:: cp.ndarray

rotation

Rotation to be applied to the generated points.

Type:: cp.ndarray

dtype

The desired data type of the returned array.

Type:: type

seed

Seed for the random number generator.

Type:: int | None

Methods:

Generates photon positions.

generate(n)

Generates photon positions.

Parameters:: n (int) – Number of photon positions to generate.
Returns:: positions – A CuPy array of shape (n, 3) where each row represents a photon position vector (x, y, z).
Return type:: cp.ndarray
Raises:: ValueError – If n is not a positive integer.

class iactsim.optics.sources.positions.PointLike(position, rotation=None, dtype=cp.float32, seed=None)

Represents a point source by generating a set of identical 3D points.

This class creates an array of n identical 3D points, all located at the specified position.

Parameters:

position (tuple, list, or cp.ndarray, shape (3,)) – The (x, y, z) coordinates of the point source. Can be a tuple, list, or CuPy array.
dtype (type, optional) – The desired data type of the returned array. Defaults to cp.float32.
seed (int | None, optional) – Seed for the random number generator.

Raises:

ValueError – If position is not a 3-element tuple, list, or CuPy array.

class iactsim.optics.sources.positions.UniformDisk(r_min, r_max, position=cp.asarray([0., 0., 0.]), rotation=None, radial_uniformity=False, random=True, seed=None, dtype=cp.float32)

Generates uniformly distributed points on a disk (or annulus) parallel to the x-y plane.

Parameters:

r_min (float) – Minimum radius of the disk (or annulus). If r_min > 0, it defines the inner radius of an annulus.
r_max (float) – Maximum radius of the disk (or annulus). Defines the outer radius.
position (array_like, shape (3,)) – Center of the disk (or annulus) in Cartesian coordinates. Can be a list, tuple, NumPy array or CuPy array.
radial_uniformity (bool, optional) – If True (default), uses a radial uniform distribution. If False, uses a uniform distribution in area.
random (bool, optional) – If True (default), generates random points. If False, generates a grid of points.
seed (int | None, optional) – A seed to initialize the random number generator.
dtype (type, optional) – Desired data type of the output array, by default cp.float32.

Raises:

ValueError – If position does not have a length of 3. If r_min is not >= 0 and less than r_max.
TypeError – If position is not a list, tuple, NumPy array or CuPy array.

class iactsim.optics.sources.positions.UniformSphericalCap(radius, angular_extent, seed=None, position=cp.asarray([0., 0., 0.]), rotation=None, dtype=cp.float32)

Generates uniformly distributed points on a spherical cap.

The spherical cap is defined by its center (position), radius, and an angular extent (or “opening angle”). Points are uniformly distributed over the cap surface and are generated symmetrically around the z-axis, relative to the center.

Parameters:

position (array_like, shape (3,)) – The center of the sphere in Cartesian coordinates (x, y, z). Can be a list, tuple, NumPy array or CuPy array.
radius (float) – The radius of the sphere.
angular_extent (float) – The opening angle of the cap in degrees, measured from the positive z-axis. Must be between 0 and 180 degrees.
seed (int | None, optional) – An optional seed for the random number generator. If None, the generator is seeded using unpredictable data from the operating system.
dtype (type, optional) – The desired data type of the returned array (default: np.float32).

Raises:

ValueError – If angular_extent is not within the range [0, 180]. If position does not have a length of 3.
TypeError – If position is not a list, tuple, or ndarray.

Classes:

`AbstractPhotonDirections`(altitude, azimuth)	Abstract base class for a photon source direction generator.
`GaussianBeam`(altitude, azimuth, dispersion)	Generates direction vectors with a Gaussian distribution around a central direction.
`PointLike`(altitude, azimuth[, dtype])	Generates a set of identical direction vector from a source specified in horizontal coordinates.
`UniformBeam`(altitude, azimuth, half_aperture)	Generates uniformly distributed directions within a cone around a central direction.

class iactsim.optics.sources.directions.AbstractPhotonDirections(altitude, azimuth, dtype=cp.float32, seed=None)

Abstract base class for a photon source direction generator.

This class defines the interface for generating photon directions, specified by altitude and azimuth angles.

altitude

Altitude angle of the source (in degrees).

Type:: float

azimuth

Azimuth angle of the source (in degrees).

Type:: float

Methods:

Generates photon direction vectors.

Attributes:

seed

Seed to initialize the CuPy random number generator (cuRAND Philox4x3210).

abstractmethod generate(n)

Generates photon direction vectors.

Parameters:: n (int) – Number of photon directions to generate.
Returns:: directions – A CuPy array of shape (n, 3) where each row represents a photon direction vector (unit vector).
Return type:: cp.ndarray
Raises:: ValueError – If n is not a positive integer.

property seed: Seed to initialize the CuPy random number generator (cuRAND Philox4x3210).

class iactsim.optics.sources.directions.GaussianBeam(altitude, azimuth, dispersion, seed=None, dtype=cp.float32)

Generates direction vectors with a Gaussian distribution around a central direction.

This class generates n direction vectors sampled from a Gaussian distribution centered around the direction specified by altitude and azimuth. The spread of the distribution is controlled by dispersion.

Parameters:

altitude (float) – Altitude angle of the beam center in degrees.
azimuth (float) – Azimuthal angle of the beam center in degrees.
dispersion (float) – Standard deviation (sigma) of the Gaussian distribution in degrees.
seed (int | None, optional) – A seed to initialize the CuPy random number generator (cuRAND Philox4x3210). If None, the generator is seeded using unpredictable data from the operating system.
dtype (data-type, optional) – Desired output data-type. Default is cp.float32.

Methods:

Generates the direction vectors sampled from a Gaussian beam.

generate(n)

Generates the direction vectors sampled from a Gaussian beam.

Parameters:: n (int) – Number of direction vectors to generate. Must be a positive integer.
Returns:: vs – An array of n unit vectors representing the directions sampled from the Gaussian beam in a right-handed Cartesian coordinate system.
Return type:: ndarray, shape (n, 3)
Raises:: ValueError – If n is not a positive integer.

class iactsim.optics.sources.directions.PointLike(altitude, azimuth, dtype=cp.float32)

Generates a set of identical direction vector from a source specified in horizontal coordinates.

This class creates an array of n identical unit vectors that represent the direction of a source specified by its altitude and azimuth angles.

Parameters:

altitude (float) – Altitude angle of the source in degrees.
azimuth (float) – Azimuthal angle of the source in degrees (0 degrees corresponds to the positive x-axis, and the angle increases counterclockwise).
dtype (data-type, optional) – Desired output data-type. Defaults to cp.float32.

Methods:

Generates the set of identical direction vectors.

generate(n)

Generates the set of identical direction vectors.

Parameters:: n (int) – Number of identical direction vectors to generate.
Returns:: vs – An array of n identical unit vectors representing the direction of the source in a right-handed Cartesian coordinate system.
Return type:: ndarray, shape (n, 3)
Raises:: ValueError – If n is not a positive integer.

class iactsim.optics.sources.directions.UniformBeam(altitude, azimuth, half_aperture, dtype=cp.float32, seed=None)

Generates uniformly distributed directions within a cone around a central direction.

This class provides a way to generate n unit vectors that are uniformly distributed within a cone defined by a central direction (altitude, azimuth) and an aperture angle. The distribution is uniform in the sense that the probability of finding a vector within a given solid angle is proportional to that solid angle.

Parameters:

altitude (float) – Altitude angle of the central direction of the cone (in degrees).
azimuth (float) – Azimuth angle of the central direction of the cone (in degrees).
aperture (float) – Angular half-size (radius) of the cone (in degrees).
dtype (data-type, optional) – Desired data type of the output array, by default cupy.float32
seed (int | None, optional) – A seed to initialize the CuPy random number generator (cuRAND Philox4x3210). If None, the generator is seeded using unpredictable data from the operating system.

Methods:

Generates n uniformly distributed direction vectors within the cone.

generate(n)

Generates n uniformly distributed direction vectors within the cone.

Parameters:: n (int) – Number of direction vectors to generate.
Returns:: directions – A CuPy array of shape (n, 3) containing the generated direction vectors. Each row represents a unit vector (x, y, z).
Return type:: ndarray, shape (n, 3)
Raises:: ValueError – If n is not a positive integer.

optics.utils

Functions:

normalize_aspheric_coefficients(...)

Rewrite aspheric coefficients for float32 calculations.

iactsim.optics.utils.normalize_aspheric_coefficients(coefficients, half_aperture)

Rewrite aspheric coefficients for float32 calculations.

This function normalizes aspheric coefficients to ensure numerical stability when using single-precision calculations. It scales the coefficients based on the surface aperture radius to prevent potential overflow or underflow issues during calculations involving powers of the radial distance.

Parameters:

coefficients (numpy.ndarray | list | tuple) – The aspheric coefficients. It can be a NumPy array, a list or a tuple.
half_aperture (float) – The half-aperture of the surface.

Returns:

new_coefficients – A new array containing the normalized aspheric coefficients.

Return type:

numpy.ndarray

Notes

The normalization is done by multiplying each coefficient A[i] by ra^(2*(i+1)). This scaling ensures that the coefficients are adjusted appropriately for calculations involving the radial distance, which is typically normalized by the surface half-aperture.

electronics

Classes:

`CherenkovCamera`(n_pixels, waveforms, ...)	Abstract class to simulate a Cherenkov camera.
`CherenkovSiPMCamera`(n_pixels, waveforms, ...)	Base class for a Cherenkov camera that uses Silicon Photo-Multipliers (SiPMs).
`Waveform`([time, amplitude, coupling])	Represents the normalized output signal of the electronics in response to a single photon detection as a function of the time from its arrival time.

class iactsim.electronics.CherenkovCamera(n_pixels, waveforms, trigger_channels, sampling_channels, channels_time_resolution)

Abstract class to simulate a Cherenkov camera.

Parameters:

n_pixels (int) – Number of pixels.
waveforms (Union[List[Waveform], Tuple[Waveform]]) – Tuple or List of Waveform instances, one for each channel. Lists are internally converted to a tuple to ensure immutability.
trigger_channels (List[int]) – Trigger channels index.
sampling_channels (List[int]) – Sampling channels index.
channels_time_resolution (List[float]) – Time resolution of each channel.

Notes

Unit Consistency

The simulation does not enforce a specific system of physical units, but it strictly requires internal consistency. It is entirely the user’s responsibility to ensure that all input parameters (time windows, resolutions, rates, etc.) align.

Crucially, rates must be expressed as the number of events per chosen unit of time. For example: if your time inputs are in nanoseconds, rates must be provided in events per ns (i.e. GHz).

Random Seed Handling

The camera manages random number generation for stochastic processes (e.g., cross-talk, background noise) on a per-pixel basis. The seed for each pixel is derived from a single uint64 master seed, base_seed, to ensure reproducibility. This behavior is controlled by the following attributes:

base_seed: The master seed that can be set by the user for reproducibility.
random_seed: If True (default), a new random value for base_seed is generated at each restart() call. This ensures that different simulation runs are independent. When set to False, base_seed is reset to 0.
increment_seed: If True (default), the base_seed is incremented by n_pixels after each simulate_response() call. This provides different random sequences for consecutive events within the same run.

If you need to manually update the per-pixel seeds you can increase the base_seed value by n_pixels, in order to have always a different seed per pixel.

Auxiliary Channels

Any channel that is not explicitly passed in trigger_channels or sampling_channels is automatically classified as an auxiliary channel. The camera manages their dynamic time windows (via auxiliary_delay and auxiliary_window_extent), but it does not automatically compute their signals. Developers must explicitly request their computation by overriding methods like sampling_action() or post_sampling_action() and calling self.compute_signals(self.auxiliary_channels) (or a specific channel needed).

Methods:

`apply_ideal_discriminator_to_channel`(...)	Apply an ideal discriminator to a specific channel pre-computed signals.
`apply_peak_detection_to_channel`(...)	Apply peak detection to a specific channel.
`compute_signals`([channels])	Method to compute signals of each pixel for the desired channels.
`get_channel_signals`(channel[, reshape])	Retrieves the signals for a specified channel.
`post_sampling_action`()	Optional action that is performed right after the sampling action.
`post_trigger_action`()	Optional action that is performed right after the trigger action, regardless if a camera trigger is generated.
`pre_sampling_action`()	Compute signals for sampling channels.
`pre_trigger_action`()	Compute signals for trigger channels.
`prepare_time_windows`([tmin, tmax])	Generate dynamic time windows and copy mapping data to the GPU device.
`sampling_action`()	Digitise the signals.
`simulate_response`([source, tmin, tmax])	Simulates the camera response to a given source of photo-electrons.
`trigger_action`()	Generates a camera trigger.

Attributes:

`auxiliary_channels`	Auxiliary channels list.
`auxiliary_delay`	Delay of the auxiliary time windows with respect to the camera trigger.
`auxiliary_window_extent`	Auxiliary windows extent.
`background_rate`	Count rate (background noise) per pixel.
`base_seed`	Run-wise seed from wich per-pixel seeds are generated.
`channels_gain`	Gain of each channel.
`channels_time_resolution`	Time resolution for each channel.
`enable_camera_trigger`	Whether to enable the camera trigger or skip directly to the sampling phase (in this case a trigger time must be provided).
`fixed_time_windows`	Whether time windows should be computed for each event or assumed fixed.
`increment_seed`	Whether to increment the seed at each `simulate_response()` call.
`n_channels`	Number of channels.
`n_pixels`	Number of pixels in the camera.
`pixel_mask`	Pixel mask.
`random_seed`	Whether to generate a random seed.
`sampling_channels`	Sampling channels list.
`sampling_delay`	Delay of the sampling time windows with respect to the camera trigger.
`sampling_window_extent`	Sampling windows extent.
`signals`	Computed signals buffer.
`source`	Input photo-electrons arrival times.
`time_windows`	Time windows where to simulate the signal.
`timer`	Benchmark timer instance.
`trigger_channels`	Trigger channels list.
`trigger_time`	Time of the last trigger.
`trigger_window_end_offset`	Trigger channels window end offset with respect to the last photo-electron arrival time in `source`.
`trigger_window_start_offset`	Trigger channels window start offset with respect to the first photo-electron arrival time in `source`.
`triggered`	Whether the camera has been triggered.
`waveforms`	Single photo-electron waveform of each channel.

apply_ideal_discriminator_to_channel(channel, thresholds, offset, time_slices_over_threshold)

Apply an ideal discriminator to a specific channel pre-computed signals.

This method implements an ideal discriminator on the waveforms of a given channel. It compares the input signal against per-pixel thresholds and sets the output signal based on whether the input signal exceeds the threshold for at least a specified number of consecutive time slices.

Parameters:

channel (int) – The channel number to process.
thresholds (cp.ndarray) – A CuPy 1D array of thresholds, one for each pixel. This array should have a dtype of cp.float32.
offset (cp.ndarray) – A CuPy 1D array of threshold offsets, one for each pixel. This array should have a dtype of cp.float32.
time_slices_over_threshold (int) – The minimum number of consecutive time slices the signal must be above the threshold to trigger a positive output. This value is assumed for all pixels.

Returns:

A CuPy array of the same shape as the input signal, containing the output of the ideal discriminator. The output will be 0.0f where the signal is below the threshold (or doesn’t stay above threshold long enough) and 1.0f where it is above the threshold.

Return type:

cp.ndarray

Examples

n_pixels = camera.n_pixels
thresholds = cp.random.rand(n_pixels).astype(cp.float32) * 10
offset = cp.zeros((n_pixels), dtype=cp.float32)
min_time_slices = 10
channel_num = 0

output_signal = camera.apply_ideal_discriminator_to_channel(channel_num, thresholds, offset, min_time_slices)
# output_signal now contains the discriminated signal for channel 0.

apply_peak_detection_to_channel(peak_amplitudes, peaking_times, channel, t_start, extent)

Apply peak detection to a specific channel.

This method processes the pre-computed signals for a given channel using peak_detection kernel to identify peaks and store their amplitudes and times.

Parameters:

peak_amplitudes (cp.ndarray) – A CuPy array where the detected peak amplitudes will be stored. This array should be pre-allocated with a size equal to the number of pixels and have a dtype of cp.float32. It can be allocated once as class attribute.
peaking_times (cp.ndarray) – A CuPy array where the detected peaking times will be stored. This array should be pre-allocated with a size equal to the number of pixels and have a dtype of cp.float32. It can be allocated once as class attribute.
channel (int) – The channel number to process.
t_start (float) – The starting time of the peak detection time window (in ns).
extent (float) – The duration of the peak detection time window (in ns).

Return type:

(numpy.ndarray,numpy.ndarray,numpy.ndarray,numpy.ndarray)

Examples

n_pixels = camera.n_pixels
peak_amps = cp.empty((n_pixels,), dtype=cp.float32)
peak_times = cp.empty((n_pixels,), dtype=cp.float32)
channel_num = 0
t_start = 0.0
duration = 100.0
camera.apply_peak_detection_to_channel(peak_amps, peak_times, channel_num, t_start, duration)
# peak_amps and peak_times now contain the results for channel 0.

auxiliary_channels: Auxiliary channels list.

auxiliary_delay: Delay of the auxiliary time windows with respect to the camera trigger. One for each auxiliary channel.

auxiliary_window_extent: Auxiliary windows extent. One value for each auxiliary channel.

property background_rate

Count rate (background noise) per pixel.

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property base_seed: Run-wise seed from wich per-pixel seeds are generated.

channels_gain: Gain of each channel.

channels_time_resolution: Time resolution for each channel.

abstractmethod compute_signals(channels=None)

Method to compute signals of each pixel for the desired channels.

Parameters:: channels (list of channel indices) – If None compute signals of all channels. By default None.

Notes

The specific computing logic is left to the concrete implementations. However, implementations should ensure that the signal is only computed for the specified channels and stored in the signals attribute array. If channels is None or empty the method must return immediately.

enable_camera_trigger: Whether to enable the camera trigger or skip directly to the sampling phase (in this case a trigger time must be provided).

fixed_time_windows: Whether time windows should be computed for each event or assumed fixed.

get_channel_signals(channel, reshape=False)

Retrieves the signals for a specified channel.

Parameters:

channel (int) – The channel number for which to retrieve signals.
reshape (bool, optional) – If True, reshapes the output array to have dimensions (n_pixels, number of time windows). If False, returns a 1D array. Default is False.

Returns:

A CuPy array containing the signals for the specified channel. The shape of the array depends on the reshape parameter.

Return type:

cp.ndarray

Raises:

RuntimeError – If the time window has not been defined for the specified channel.

increment_seed: Whether to increment the seed at each simulate_response() call.

n_channels: Number of channels.

property n_pixels: Number of pixels in the camera.

pixel_mask: Pixel mask. Pixel with value 1 are ignored.

post_sampling_action(): Optional action that is performed right after the sampling action. This method is called only if a trigger condition is met or if the camera trigger is disabled.

post_trigger_action(): Optional action that is performed right after the trigger action, regardless if a camera trigger is generated. This method is called only if the camera trigger is enabled.

pre_sampling_action(): Compute signals for sampling channels.

pre_trigger_action(): Compute signals for trigger channels.

prepare_time_windows(tmin=None, tmax=None)

Generate dynamic time windows and copy mapping data to the GPU device.

This method manages a two-phase memory and window initialization lifecycle for all camera channels (trigger, sampling, and auxiliary). To maximize performance, it minimizes GPU memory re-allocation overhead by reusing pre-allocated device buffers whenever possible.

Parameters:

tmin (float or cupy.ndarray, optional) – The minimum photon arrival time for the current event. If None, it is dynamically calculated from the minimum value in self.source[0]. Defaults to None.
tmax (float or cupy.ndarray, optional) – The maximum photon arrival time for the current event. If None, it is dynamically calculated from the maximum value in self.source[0]. Defaults to None.

Notes

The method execution is split into two logical stages based on the triggered status flag:

Pre-Trigger (self.triggered == False): Evaluates bounds for the trigger channels and builds their timeline arrays. For sampling and auxiliary channels, it calculates their anticipated allocation sizes.
Post-Trigger (self.triggered == True): Trigger time is now known. The method loops back through the uninitialized sampling and auxiliary channels to construct their delayed timeline arrays relative to trigger_time.

When calling simulate_response() method this function is automatically called before computing trigger signals (i.e. before the pre_trigger_action() call) and before computing sampling signals (i.e. after a trigger and before the pre_sampling_action() call). If you want to implement a simulation pipeline replacing simulate_response(), remember to call this function before computing trigger signals (when self.triggered == False) and before computing sampling signals (when self.triggered == True).

property random_seed: Whether to generate a random seed.

abstractmethod sampling_action()

Digitise the signals.

Notes

The specific logic is left to the concrete implementations. This method is called only if a trigger condition is met or if the camera trigger is disabled.

sampling_channels: Sampling channels list.

sampling_delay: Delay of the sampling time windows with respect to the camera trigger. One for each sampling channel.

sampling_window_extent: Sampling windows extent. One value for each sampling channel.

signals: Computed signals buffer.

simulate_response(source=None, tmin=None, tmax=None)

Simulates the camera response to a given source of photo-electrons.

This method controls the simulation process:

Getting the source.

Preparing time windows for trigger channels.

Triggering actions (pre, trigger, post).

Preparing time windows for channels to be sampled.

Sampling actions (pre, sampling, post).

If enable_camera_trigger is True, the pre_trigger_action(), trigger_action(), and post_trigger_action() methods are called in sequence. pre_trigger_action() computes the signals of all trigger channels. If a trigger occurs (as determined by trigger_action()), or if camera triggering is disabled, the sampling phase starts.

Parameters:

source (Tuple[cp.ndarray, cp.ndarray], optional) –
A tuple containing:
- pes: A 1D CuPy array of shape (total_n_pes,) containing the arrival times of all photo-electrons.
- pes_map: A 1D CuPy array of shape (n_pixels + 1,) representing a mapping to access the arrival times for each pixel. The arrival times for pixel i are given by pes[pes_map[i]:pes_map[i+1]].
If None only the background is simulated.
tmin (float, optional) – Minimum arrival time in source to consider for the dynamic time window generation. If None, the minimum arrival time in source is used. Pass this to avoid device-host synchronization.
tmax (float, optional) – Maximum arrival time in source to consider for the dynamic time window generation. If None, the maximum arrival time in source is used. Pass this to avoid device-host synchronization.

Raises:

RuntimeError – If camera triggering is disabled (enable_camera_trigger is False) and trigger_time is not set (i.e., is None). This ensures that a valid trigger time is available for the sampling phase.

Notes

The method also increments an event counter (self._event_counter) after each simulation.

If increment_seed is true, the random seed (base_seed) is incremented by n_pixels after each simulation. This helps ensure that the simulation of different events produces different random values (e.g. background and cross-talk generation).

The following methods are called during the simulation:

If camera triggering is enabled:

pre_trigger_action(): compute all signals for trigger channels.

trigger_action(): Performs the trigger logic (should set triggered and trigger_time attributes).

post_trigger_action(): Actions after the trigger.

If triggered is True or camera triggering is disabled (and a custom trigger time is provided):

pre_sampling_action(): compute all signals for sampling channels (and auxiliary channels if compute_auxiliaries_alongside_sampling is True).

sampling_action(): Performs the sampling.

post_sampling_action(): Actions after sampling.

In both case 1 and 2, methods b,c must be implemented by the user if a base abstract class is used.

property source: Input photo-electrons arrival times.

time_windows: Time windows where to simulate the signal. One for each channel.

timer: Benchmark timer instance.

abstractmethod trigger_action()

Generates a camera trigger.

Notes

Concrete implementations of this method should contain the logic to determine when a camera trigger has been be generated. If the trigger condition is met, implementations must ensure that:

the triggered attribute is set to True.

the trigger_time attribute is set to the time representing the moment when the trigger condition was met.

This method is called only if the camera trigger is enabled.

trigger_channels: Trigger channels list.

trigger_time: Time of the last trigger.

trigger_window_end_offset: Trigger channels window end offset with respect to the last photo-electron arrival time in source.

trigger_window_start_offset: Trigger channels window start offset with respect to the first photo-electron arrival time in source.

triggered: Whether the camera has been triggered.

property waveforms: Tuple[Waveform, ...]: Single photo-electron waveform of each channel.

class iactsim.electronics.CherenkovSiPMCamera(n_pixels, waveforms, trigger_channels, sampling_channels, channels_time_resolution)

Base class for a Cherenkov camera that uses Silicon Photo-Multipliers (SiPMs). Inherits from CherenkovCamera and implements virtual methods specific to SiPMs.

Attributes:

`afterpulse`	Probability of a microcell generating an afterpulse.
`afterpulse_inv_tau`	Inverse of the afterpulse time constant.
`cross_talk`	Optical cross-talk probability between microcells (for example 0.06).
`inv_tau_recovery`	Inverse of the microcell recovery time constant.
`n_ucells`	Number of microcells per pixel.
`pixel_mask`	Pixel mask array.
`sigma_ucells`	Relative standard deviation of the single microcell response amplitude (for example 0.01, i.e. 1%).
`simulate_ucells`	Whether to explicitly simulate the finite number of microcells.

Methods:

`compute_signals`([channels])	Compute SiPM signals for the specified channels.
`sampling_action`()	Digitise the signals.
`trigger_action`()	Generates a camera trigger.

property afterpulse

Probability of a microcell generating an afterpulse.

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property afterpulse_inv_tau

Inverse of the afterpulse time constant.

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

compute_signals(channels=None)

Compute SiPM signals for the specified channels.

Parameters:: channels (List[int], optional) – Channels IDs, by default computes all channels.

property cross_talk

Optical cross-talk probability between microcells (for example 0.06).

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property inv_tau_recovery

Inverse of the microcell recovery time constant.

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property n_ucells

Number of microcells per pixel.

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property pixel_mask: Pixel mask array. Pixels with a value of 1 are ignored during processing.

abstractmethod sampling_action()

Digitise the signals.

Notes

The specific logic is left to the concrete implementations. This method is called only if a trigger condition is met or if the camera trigger is disabled.

property sigma_ucells

Relative standard deviation of the single microcell response amplitude (for example 0.01, i.e. 1%).

Can be specified as a single scalar (applied to all pixels) or an array of length n_pixels for per-pixel configuration.

property simulate_ucells: Whether to explicitly simulate the finite number of microcells.

abstractmethod trigger_action()

Generates a camera trigger.

Notes

Concrete implementations of this method should contain the logic to determine when a camera trigger has been be generated. If the trigger condition is met, implementations must ensure that:

the triggered attribute is set to True.

the trigger_time attribute is set to the time representing the moment when the trigger condition was met.

This method is called only if the camera trigger is enabled.

class iactsim.electronics.Waveform(time=None, amplitude=None, coupling=None)

Represents the normalized output signal of the electronics in response to a single photon detection as a function of the time from its arrival time. Is assumed to be 0 outside the defined time window.

The waveform is automatically normalized upon initialization based on the provided coupling.

Parameters:

time (numpy.ndarray) – Array of time values corresponding where the waveform is defined, must be monotonically increasing.
amplitude (numpy.ndarray) – Array of waveform amplitudes corresponding to the time array.
coupling (str) –
Coupling of the signal. Must be “AC” or “DC” (case insensitive). This determines the default normalization scheme applied at initialization:
- ”AC”: normalize by the waveform peak;
- ”DC”: normalize by the waveform integral.

Notes

A “dummy” waveform can be created using the default None arguments:

dummy_wave = Waveform()

Raises:

TypeError – If the input argument are not Numpy ndarray.
ValueError – If the input argument have more than one dimension.
ValueError – If the input argument do not have the same length.
ValueError – If the time array is not monotonically increasing.
ValueError – If the time array is not equispaced.
ValueError – If the signal coupling is not valid.

Attributes:

`amplitude`	Returns the amplitude array.
`coupling`	Returns the signal coupling.
`time`	Returns the time array.

Methods:

`get_extent`()	Returns the waveform time-extent.
`get_integral`()	Returns the approximate integral of the waveform using the trapezoidal rule.
`get_peak_amplitude`()	Returns the peak amplitude of the waveform.
`get_peak_time`()	Returns the time corresponding to the peak amplitude of the waveform.
`get_size`()	Returns the waveform number of time bins.
`get_squared_integral`()	Returns the approximate integral of the squared waveform using the trapezoidal rule.
`load_json`(file_path)	Creates a Waveform instance from a JSON file.
`normalize`([norm])	Normalize the waveform amplitude.
`save_json`(file_path[, comment])	Saves the current waveform configuration to a JSON file.

property amplitude: Returns the amplitude array.

property coupling: Returns the signal coupling.

get_extent()

Returns the waveform time-extent.

Return type:: float

get_integral()

Returns the approximate integral of the waveform using the trapezoidal rule.

Return type:: float

get_peak_amplitude()

Returns the peak amplitude of the waveform.

Return type:: float

get_peak_time()

Returns the time corresponding to the peak amplitude of the waveform.

Return type:: float

get_size()

Returns the waveform number of time bins.

Return type:: int

get_squared_integral()

Returns the approximate integral of the squared waveform using the trapezoidal rule.

Return type:: float

classmethod load_json(file_path)

Creates a Waveform instance from a JSON file.

Parameters:: file_path (str) – Path to the JSON file containing ‘time’, ‘amplitude’, and ‘coupling’.

normalize(norm=None)

Normalize the waveform amplitude.

This method is automatically called during initialization.

Parameters:: norm (float, optional) – Normalization factor. If None, it is determined based on the coupling type assigned at initialization. For ‘AC’ coupling, the waveform is normalized to the peak amplitude. For ‘DC’ coupling it’s normalized to the integral. By default, None.

save_json(file_path, comment='')

Saves the current waveform configuration to a JSON file.

Parameters:

file_path (str) – Path where the JSON file will be saved.
comment (str, optional) – A comment to be added at the top of the JSON file.

property time: Returns the time array.

electronics.signals

signals.discriminator_signals

Functions:

`count_pixel_triggers`	Counts the number of rising edges (pixel triggers) in a discriminator signal.
`ideal_discriminator`	Simulates an ideal discriminator response.
`last_trigger_time_counter_from_camera_trigger`	Counts clock cycles between the last pixel trigger and the camera trigger.

iactsim.electronics.signals.discriminator_signals.count_pixel_triggers()

Counts the number of rising edges (pixel triggers) in a discriminator signal.

This kernel function takes an array of signals and counts the number of times the signal crosses a threshold (0.5) from below to above, indicating a rising edge or pixel trigger. It operates on a per-pixel basis, processing a window of the signal for each pixel. The kernel assumes ideal rising edges with negligible rising time.

Parameters:

counts (int*) – An output array of integers, where the count of rising edges for each pixel will be stored. This array should have a size of n_pixels. The counts are added to the existing values in this array.
signals (const float*) – A constant input array of floats representing the signals for each pixel. This array should contain n_pixels X window_size elements, where each pixel signal occupies a contiguous block of window_size elements.
window_size (int) – An integer representing the size of the window for each pixel signal.
n_pixels (int) – An integer representing the number of pixels to process.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.electronics.signals.discriminator_signals.ideal_discriminator()

Simulates an ideal discriminator response.

This kernel processes an input signal and generates a discriminator output signal based on a given threshold. It also applies a minimum pulse width filter.

The kernel operates with one block per pixel. Each thread within a block processes a portion of the pixel time window. Discriminator Logic:

If the input_signal is above the pixel threshold AND the pixel is not masked (mask[bid] == 0) the output_signal for that time slice is set to 1.0; otherwise the output_signal is set to 0.0. Pulse Width Filter:

After the initial discriminator signal is computed, a pulse-width filter is applied within each block (pixel) to search for consecutive time slices where the output_signal is 1.0. If the number of consecutive slices over threshold is less than time_slices_over_threshold, those slices in the output_signal are reset to 0.0. This effectively removes short pulses. Assumptions/Approximations:

Zero rising and falling time.

Parameters:

input_signal (const float*) – Input signal data with n_pixels X time_window_size elements.
output_signal (float*) – Output discriminator signal data. This array should be pre-allocated with the same size as the relevant portion of the input signal. The array does not need to be initialized.
threshold (const float*) – Threshold value for each pixels. The length of this array should equal n_pixels.
offset (const float*) – Discriminator offset for each pixel. The length of this array should equal n_pixels.
time_slices_over_threshold (int) – Minimum number of consecutive time slices that the input signal must be above the threshold to generate a trigger signal.
mask (const int*) – Array indicating whether a pixel is masked (1) or active (0). Masked pixels will not generate triggers.
time_window_size (int) – The number of time slices in the signal time window.
n_pixels (int) – The total number of pixels.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.electronics.signals.discriminator_signals.last_trigger_time_counter_from_camera_trigger()

Counts clock cycles between the last pixel trigger and the camera trigger.

This function simulates a time-to-digital converter (TDC) counter to measure the time between the last trigger of each pixel and the camera trigger. The trigger time for each pixel is determined by counting the number of clock cycles (time bins) between the camera trigger and the last rising edge of the pixel discriminator signal. The counting starts from the beginning of the window and continues up to stop_clock cycles after the camera trigger clock camera_trigger_time_index. The result, representing the time difference, is stored as an integer in an array that emulates a register with register_n_bits bits (maximum of 32).

Parameters:

trigger_times (int*) – Output array of integers. Stores the calculated trigger times for each pixel. The size of this array should be equal to n_pixels. Each element represents the time difference in clock cycles, mapped to the range of the register_n_bits-bit register. A value of 0 indicates no trigger was found within the search window. A value of (2^register_n_bits) - 1 indicates an overflow.
signals (const float*) – Input array of floats representing the discriminator signals for each pixel. The size of this array should be n_pixels * window_size. The signal for pixel i is stored in signals[i * window_size] to signals[(i + 1) * window_size - 1]. A rising edge (transition from < 0.5 to > 0.5) indicates a trigger.
camera_trigger_time_index (int) – Integer representing the clock cycle index at which the camera trigger occurs. This serves as the reference time (time 0+2^(register_n_bits-1))) for all pixel trigger time calculations.
stop_clock (int) – Integer representing the number of clock cycles after the camera trigger during which the function will search for pixel triggers. The search window for each pixel is from camera_trigger_time_index to camera_trigger_time_index + stop_clock.
register_n_bits (int) – Integer representing the number of bits in the simulated TDC register. This determines the range of values that can be stored in trigger_times. Valid values are between 1 and 32 (inclusive).
window_size (int) – Integer representing the number of time bins in the discriminator signal for each pixel.
n_pixels (int) – Integer representing the total number of pixels.

Warning

The function assumes ideal rising edges with a negligible rise time (<<clock).
The function uses shared memory for inter-thread communication within a block.
The size of the shared memory required is 4 * (window_size + blockDim.x) bytes.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

signals.sipm_signals

Functions:

sipm_signals

Computes the formed SiPM signals.

iactsim.electronics.signals.sipm_signals.sipm_signals()

Computes the formed SiPM signals.

This kernel function simulates the response of Silicon Photo-Multipliers (SiPMs) by superimposing single photo-electron (PE) waveforms based on PE arrival time, SiPM cross-talk, SiPM microcells gain dispersion and SiPM PE-background noise. It operates on a per-pixel and per-active-channel basis, assigning a CUDA block per pixel per active channel.

The kernel is launched with a 1D grid of blocks, where each block is responsible for computing the signal for a single (pixel, active_channel) combination. Because the grid only launches for active channels, the block ID (bid) is a relative index. The kernel internally computes absolute_idx to correctly index into global arrays spanning all channels. Each block uses shared memory (shared_buffer) to store the intermediate signal, improving performance by reducing global memory accesses.

The signal computation involves the following steps:

Determine the block assigned channel and pixel. Initialize the shared memory buffer to zero.
Input signal

2a. Initialize a curandStatePhilox4_32_10_t random number generator for the pixel using the provided seed. Each pixel has a unique seed per event. This allows the signals of each channel to be computed in different stages.

2b. Iterate through the photon arrival times associated with the current pixel. For each photon:

calculate the number of cross-talk photons using a Borel distribution;

calculate the microcell gain variation, incorporating gain dispersion using a normal distribution;

superimpose the single-photon waveform onto the shared memory buffer, interpolating the channel waveform.

Background signal

3a. Re-initialize the curandStatePhilox4_32_10_t random number generator with a seed per thread. 3b. Heach thread generates a background noise event extracting - a number of cross-talk photons; - a micro-cell gain; - a poissoninan inter-arrival time; 3c. The actual time is computed with a parallel cumulative sum of all extracted times. All generated events are stored in shared memory.

3d. Generated events are processed one-by-one. The signal accross the time-window is updated in parallel in the shared memory buffer.

Copy the computed signal from the shared memory buffer to the global signals array.

Parameters:

windows (const float*) – Array of time windows for each channel. Defines the time ranges over which signals are computed. windows[windows_map[channel] : windows_map[channel+1]] is the time window for channel.
windows_map (const int*) – Array indicating the starting and ending index of the time window for each channel within the windows array.
signals (float*) – Output array where the computed SiPM signals are stored. The signal for a given channel and pixel is stored in a contiguous block. signals[start_signals[channel] + pixel_id * n_window : start_signals[channel] + (pixel_id + 1) * n_window] where n_window = windows_map[channel+1] - windows_map[channel]. The array does not need to be initialized before the kernel invocation.
signals_map (const int*) – Array indicating the starting index and ending index of each channel inside the array signals.
active_channels (const int*) – Array of channel IDs to actually compute (e.g., [1, 2]).
n_active_channels (int) – Length of the active_channels array (e.g., 2).
n_channels (int) – Total number of channels in the camera geometry.
t0s (const float*) – Array of discharge times for each pixel.
map (const int*) – Array that maps pixel indices to the range of their corresponding discharge times in the t0s array. Specifically, t0s[map[pixel_id]:map[pixel_id+1]] provides the discharge times for pixel_id.
waveforms (Unknown) – Array containing the texture pointer of all channel waveforms.
inv_dt_waveforms (const float*) – Array containing the inverse of the time spacing (dt) for each waveform.
t_start_waveforms (const float*) – Array indicating the starting time of each waveform.
gains (const float*) – Array containing the pulse peak amplitued for each pixel for each channel (n_pixels*n_channels size)
xt (const float*) – Array of cross-talk probabilities for each pixel. This represents the probability that a discharge in one microcell will trigger a discharge in an adjacent microcell.
std_ucells (const float*) – Array of microcell gain dispersions for each pixel. This models the variation in the charge produced by different microcells for a single photon.
mask (const int*) – Array indicating whether a pixel is masked (1) or active (0). Masked pixels will have zero signal.
inv_bkg_rate (const float*) – Array of inverse background rates for each pixel (in units of time). This is used to generate background noise events.
bkg_start (float) – Start time for background noise generation.
bkg_end (float) – End time for background noise generation.
seed (unsigned long long) – Array of random number generator seeds, one for each pixel.
n_pixels (int) – Number of pixels.

Warning

The number of blocks must be n_pixels*n_active_channels (i.e. a block per pixel per active channel).
The size of the shared memory buffer must be equal to (max_window_size+n_threads*3 + 32) * sizeof(float).

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

signals.sampling_signals

Functions:

`digitize`	Digitizes 16-bit signals and adds digitization baseline and noise.
`peak_detection`	Detects the peak value and its corresponding time within a specified time interval for each pixel.

iactsim.electronics.signals.sampling_signals.digitize()

Digitizes 16-bit signals and adds digitization baseline and noise.

This kernel performs digitization of floating-point input signals, simulating the behavior of an Analog-to-Digital Converter (ADC). It also adds digitization Gaussian noise to the digitized signal.

Parameters:

digitized_output (unsigned short*) – Pre-allocated output array to store the digitized signals. Size: n_pixels * time_window_size. The data type is unsigned short, representing the 16-bit digitized values. The array does not need to be initialized.
input_signals (const float*) – Input array containing the floating-point signal data for all pixels. Size: n_pixels * time_window_size.
offset (const float*) – Input array containing the baseline of the digitised signal for each pixel.
noise (const float*) – Input array containing the per-pixel noise factors. Size: n_pixels. These values scale the standard deviation of the normally distributed noise added to each pixel.
seed (unsigned long long) – Input array of seeds for the per-pixel pseudo-random number generators. Size: n_pixels. Using different seeds for each pixel ensures uncorrelated noise.
adc_max (int) – The maximum value that the ADC can represent (saturation level). This should correspond to the maximum value of 2^n-1 for a n-bit ADC (up to 16-bit).
n_pixels (int) – The total number of pixels.
time_window_size (int) – The number of time samples in the time window (i.e.: the number of samples per pixel in the input_signals and digitized_output arrays).

Notes

The data (digitized_output and input_signals) is organized such that all time samples for pixel 0 are contiguous, followed by all time samples for pixel 1 and so on.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.electronics.signals.sampling_signals.peak_detection()

Detects the peak value and its corresponding time within a specified time interval for each pixel.

This kernel function implements a parallel peak detection algorithm. The algorithm searches for the maximum signal value within a peak-detection window for each pixel. This peak-detection window is a sub-interval of the global time window covered by the entire signal.

The algorithm works as follows:

The kernel uses one block per pixel. Each thread within a block is responsible for processing a sub-window of the global time window, defined by the time_window array.
Threads within a block cooperate using shared memory. Each thread finds the maximum value within its assigned sub-window of the global time window and stores it, along with the corresponding time, in shared memory.
A reduction is performed to find the maximum of these intermediate maxima (from shared memory) in order to determine the global peak for the pixel within the specified peak-detection window [t_start, t_start+extent].
For each pixel the peak value and its corresponding time are written to global memory arrays. The global time window is represented by the time_window array, which contains the time values for all signals. The peak-detection window is defined by the t_start and extent parameters. The peak is searched for only within the interval [t_start, t_start + extent]. This allows for focused peak detection within a specific region of interest. The global time window is divided among the available threads. Each thread finds a sub-window maximum and stores it in a shared array th_peaks_and_times. Thread 0 then finds the maximum of th_peaks_and_times and stores the result in the global memory arrays peak_amplitudes and peak_time. The shared array is allocated dynamically. The total shared memory needed is 8 * blockDim.x bytes (2 floats per thread).

Parameters:

peak_amplitudes (float*) – Output array to store the peak signal values for each pixel. Size: n_pixels.
peak_time (Unknown) – Output array to store the time corresponding to the peak signal for each pixel. Size: n_pixels.
signals (const float*) – Input array containing the signal data for all pixels. The data is organized such that all time samples for pixel 0 are contiguous, followed by all time samples for pixel 1, and so on. Size: n_pixels * time_window_size.
time_window (const float*) – Input array containing the time values corresponding to each sample in the signals array. This defines the global time window. Size: time_window_size.
t_start (float) – The start time of the peak-detection window.
extent (float) – The duration (extent) of the peak-detection window, starting from t_start. The peak is searched for within [t_start, t_start + extent].
mask (const int*) – Input array acting as a mask. Pixels with a mask value of 1 are skipped (peak=0 and time=0). Size: n_pixels.
time_window_size (int) – The number of time samples in the time_window array (and the number of samples per pixel in the signals array). This represents the size of the global time window.
n_pixels (int) – The total number of pixels.

Warning

The number of blocks must be at least n_pixels (i.e. a block per pixel).
The number of threads must be a power of 2.
The size of the dynamic shared memory buffer must be two times the number of thread assigned to each block multiplied by 4 (i.e. 8 bytes per thread).

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

signals.trigger_logic

Functions:

`count_topological_camera_triggers`	Counts the number of camera triggers within a time window.
`topological_camera_trigger`	Computes topological triggers for the entire camera and identifies the earliest trigger time and module.

iactsim.electronics.signals.trigger_logic.count_topological_camera_triggers()

Counts the number of camera triggers within a time window.

This kernel computes a global camera trigger signal by performing a logical OR operation across all module trigger signals for each time slice. If any module is triggered at time t (signal > 0.5), the camera is considered triggered at time t. After constructing this global signal in shared memory, the kernel identifies and counts the number of rising edges (transitions from logical 0 to 1). The kernel is designed to operate within a single thread block.

Parameters:

counts (int*) – Pointer to an integer global counter. The detected number of triggers is added to this value using atomic operations. Ensure this is initialized to 0 before use.
signals (const float*) – Pointer to the global array of module trigger signals. Layout is assumed to be [n_modules * window_size], accessed as signals[module_idx * window_size + time_idx].
window_size (int) – The number of time slices in the time window.
n_modules (int) – The total number of modules in the camera.

Warning

Shared Memory: this kernel requires dynamic shared memory. The kernel launch must allocate at least window_size * sizeof(float) bytes of dynamic shared memory.
Single Block: this kernel explicitly checks blockIdx.x. Computation only occurs in Block 0. Launching with gridDim.x > 1 is valid but wasteful.
Edge Cases: a rising edge is defined as signal > 0.5 and previous <= 0.5.
counts must be initialized to 0 before kernel launch.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

iactsim.electronics.signals.trigger_logic.topological_camera_trigger()

Computes topological triggers for the entire camera and identifies the earliest trigger time and module.

This kernel processes the discriminator signals for all modules in parallel. Each thread block handles a specific module (determined by blockIdx.x), and threads within the block iterate over the time window in a grid-stride loop. For every time slice, the kernel checks if the module satisfies the topological trigger condition (a contiguous group of active pixels >= n_contiguous) using module_topological_trigger. The kernel performs two main outputs:

Signal Generation: Populates module_trigger_signals with a 1.0/0.0 trace indicating trigger status for every module and time step.

Global Trigger Identification: Finds the earliest trigger occurrence across the entire camera.

It uses atomic operations to find the global minimum of a packed 64-bit integer encoding (Time << 32) | (RandomSkip << 16) | (ModuleID)

The “RandomSkip” is used to chose randomly a module when multiple modules trigger at the exact same time, preventing bias toward lower module IDs.

The result is unpacked into the trigger input array.

Parameters:

disc_signals (float*) – Pointer to the global signal array with layout [n_modules * n_pixels * window_size]. Contains the raw discriminator outputs (float).
n_contiguous (int) – The minimum number of contiguous pixels required to form a trigger.
module_trigger_signals (float*) – Output array of size [n_modules * window_size]. Stores the binary trigger result (1.0 or 0.0) for each module/time.
trigger (int*) – Output array of size 2 (int): - trigger[0]: Time index of the earliest trigger (or -1 if none); - trigger[1]: Module ID of the earliest trigger (or -1 if none).
workspace (Unknown) – Global memory buffer for DFS operations. Must be large enough to hold stack and mask data for every thread. Size: n_modules * n_threads * (n_pixels + n_pixels/32 + 2).
window_size (int) – The length of the readout window (number of time slices).
module_dimension (int) – The width/height of a module (e.g., 8).
n_modules (int) – Total number of modules in the camera.
seed (long long int) – Seed for the random number generator used to randomly pick a module ID when multiple modules trigger at the same time.

Warning

workspace_buffer must have a size of n_modules * n_threads * (n_pixels + n_pixels/32 + 2).

Notes

This kernel requires cg::sync(grid) and thus must be launched using a cooperative launch API if the grid size exceeds the device’s maximum resident blocks, or if global synchronization is strictly required. However, the current implementation only strictly requires grid sync for the final unpacking step on thread 0.

Attention

This is a wrapped CuPy RawKernel object, you can launch it as follows:

blocks = ...  # Number of blocks
threads = ...  # Number of threads per block
shared_memory = ...  # Dynamic shared memory buffer size (if needed)
args = (...)  # Provide the arguments
kernel(grid, block, args, shared_mem=shared_memory)

If you are new to CuPy, please see the CuPy documentation.

electronics.sources

Functions:

generate_poisson_flash(n_pixels, mean, ...)

Generate Poisson arrival times in a time window equal for all pixels.

iactsim.electronics.sources.generate_poisson_flash(n_pixels, mean, t_start, duration, n_ucells=None, seed=None)

Generate Poisson arrival times in a time window equal for all pixels.

This function simulates the arrival times of photo-electrons generated by a Poisson process, representing a light flash. It assumes the same time window (start time and duration) for all pixels, but allows for a different mean number of photo-electrons for each pixel.

Parameters:

n_pixels (int) – Total number of pixels.
mean (Union[cp.ndarray, numpy.ndarray]) – Mean number of photo-electrons for each pixel. This should be a 1D array of length n_pixels.
t_start (float) – Start time of the flash (in ns).
duration (float) – Duration of the flash (in ns).
get_ucells_id (int, optional) – Number of micro-cells per pixel micro-cell IDs (for microcell simulation).
seed (int, optional) – Random seed for reproducibility. If None, a random seed is generated.

Returns:

A tuple containing:

pes: A 1D CuPy array of shape (total_n_pes,) containing the arrival times of all photo-electrons.
pes_map: A 1D CuPy array of shape (n_pixels + 1,) representing a mapping to access the arrival times for each pixel. The arrival times for pixel i are given by pes[pes_map[i]:pes_map[i+1]].

Return type:

Tuple[cp.ndarray, cp.ndarray]

Examples

import cupy as cp
n_pixels = 10
mean = cp.array([2.0, 3.5, 1.0, 4.2, 0.8, 2.7, 1.9, 3.1, 2.5, 1.3])
t_start = 0.0
duration = 10.0
pes, pes_map = generate_poisson_flash(n_pixels, mean, t_start, duration)
# Access arrival times for pixel 3:
pixel_3_times = pes[pes_map[3]:pes_map[4]]

electronics.utils

Classes:

CameraInputData(phs, pe_event_pixel_offsets, ...)

Stores photon-to-pixel mappings and arrival times for camera simulation.

class iactsim.electronics.utils.CameraInputData(phs, pe_event_pixel_offsets, pe_event_offsets, t_min, t_max, subids=None)

Stores photon-to-pixel mappings and arrival times for camera simulation. All initialization parameters are stored as public attributes of the same name.

This class acts as a sequence, allowing users to easily iterate over or index individual events. It holds the intermediate arrays generated after photon tracing, enabling deferred or batched execution of the camera response simulation.

Parameters:

phs (cupy.ndarray) – 1D array containing the arrival times of all detected photo-electrons across all events.
pe_event_pixel_offsets (cupy.ndarray) – 2D array of shape (n_events, n_pixels + 1). Contains the cumulative sum of photoelectrons per pixel for each event.
pe_event_offsets (cupy.ndarray or numpy.ndarray) – 1D array of shape (n_events + 1,). Contains the global starting and ending indices for each event slice in the phs array.
t_min (cupy.ndarray) – 1D array of shape (n_events,) containing the minimum arrival time for each event.
t_max (cupy.ndarray) – 1D array of shape (n_events,) containing the maximum arrival time for each event.
subids (cupy.ndarray, optional) – 1D array of sub-pixel IDs corresponding to each photoelectron in phs. Required if microcell simulation is enabled. Default is None.

simulate_ucells

Flag indicating whether microcell simulation data (subids attribute) is present.

Type:: bool

pe_event_offsets_host

A host copy of pe_event_offsets to allow fast indexing in Python loops without triggering device-to-host synchronizations.

Type:: numpy.ndarray

Examples

Simulate the detection of a specific event:

Loop over filtered events:

Methods:

`__getitem__`(event_idx)	Retrieve the source arrays and timing bounds for a specific event.
`__iter__`()	Iterate over the active events.
`__len__`()	Get the total number of events stored in the input data.
`__repr__`()	Generate a text-based table representation of the class statistics.
`apply_pes_threshold`(min_n_pes)	Filter the internal events based on a minimum photoelectron threshold.
`get_event_photons`(event_idx[, active_only])	Extract the photon data for all pixels in a specific event.
`get_pixel_photons`(event_idx, pixel_idx)	Extract the arrival times (and sub-pixel IDs) for a specific pixel.

Attributes:

n_active_events

Get the number of events that passed the pes threshold.

__getitem__(event_idx)

Retrieve the source arrays and timing bounds for a specific event.

Parameters:: event_idx (int) – The index of the event to retrieve.
Returns:: A tuple containing (source, t_min, t_max). source is itself a tuple of arrays required by the camera simulation: (phs_slice, pixel_offsets_slice) or (phs_slice, pixel_offsets_slice, subids_slice) if microcells are enabled. t_min and t_max are the scalar time bounds for the event.
Return type:: tuple
Raises:: IndexError – If the event_idx is out of bounds.

__iter__()

Iterate over the active events. If no threshold has been applied, it defaults to iterating over all events.

Yields:: tuple – (original_event_idx, source, t_min, t_max)

__len__()

Get the total number of events stored in the input data.

Returns:: The number of events.
Return type:: int

__repr__()

Generate a text-based table representation of the class statistics.

Returns:: Formatted ASCII table containing object statistics.
Return type:: str

apply_pes_threshold(min_n_pes): Filter the internal events based on a minimum photoelectron threshold. Sets the self.active_indices attribute for iteration.

get_event_photons(event_idx, active_only=True)

Extract the photon data for all pixels in a specific event.

Parameters:

event_idx (int) – The index of the event.
active_only (bool, optional) – If True (default), returns data only for pixels that received at least one photon. This is significantly faster and uses less memory.

Returns:

A dictionary mapping pixel_idx (int) to its photon data. The photon data format matches get_pixel_photons (either an array of times, or a tuple of (times, subids)).

Return type:

dict

get_pixel_photons(event_idx, pixel_idx)

Extract the arrival times (and sub-pixel IDs) for a specific pixel.

Parameters:

event_idx (int) – The index of the event.
pixel_idx (int) – The index of the pixel.

Returns:

If microcells are disabled, returns a 1D array of arrival times. If microcells are enabled, returns a tuple of (arrival_times, subids).

Return type:

cupy.ndarray or tuple

property n_active_events: Get the number of events that passed the pes threshold.

io

Classes:

`PathDumper`(stream, **kwargs)	Custom YAML dumper that formats Path objects with the `!path` tag.
`PathLoader`(stream)	Custom YAML loader that resolves file paths relative to the configuration file location.

class iactsim.io.PathDumper(stream, **kwargs)

Custom YAML dumper that formats Path objects with the !path tag.

If the Path object is absolute, this dumper will automatically attempt to make it relative to the directory of the file being written to.

class iactsim.io.PathLoader(stream)

Custom YAML loader that resolves file paths relative to the configuration file location.

This loader enables the use of the !path tag in YAML files. When this tag is encountered, the loader automatically resolves the specified path relative to the directory containing the YAML file, returning a pathlib.Path object.

visualization

Classes:

VTKOpticalSystem(optical_system[, resolution])

Class to viasualize the geometry of an optical system.

Functions:

`browse_images`([image_lists, geom, cmaps, ...])	An interactive widget to browse camera images or call a custom plotting function.
`camerashow`(image, geom[, ax, figsize, cmap, ...])	Plots an image of the camera using true pixel positions and shapes, mapping a 1D array of pixel values to a colormap.
`histogram2d`(vectors3d, bins[, plane, ...])	Generates and displays a 2D histogram of two components of a set of 3D vectors.
`scatter`(vectors3d[, colors_array, plane, s, ...])	Creates a scatter plot of two components of a set of 3D vectors.

class iactsim.visualization.VTKOpticalSystem(optical_system, resolution=None)

Class to viasualize the geometry of an optical system. Each surface actor can be accessed from actors attribute after a update() call.

Parameters:

optical_system (OpticalSystem or IACT) – Optical sistem for which visualize surfaces.
resolution (float, optional) – Objects mesh resolution (in mm). By default 10 mm.

Notes

If you perform some operation on an actor, make sure to call start_render() with update=False, otherwise the actors will be replaced.

Attributes:

`actors`	surface actor.
`window_size`	Window size in pixel.
`wireframe`	Whether to use wireframe representation by default.

Methods:

`add_rays`(start, stop[, surface_id, ...])	Draw rays from start to stop positions and highlight stop points.
`get_screenshot`(camera_position[, filename, ...])	Render the scene off-screen and save it to a PNG file.
`set_ray_opacity`(value)	Set the opacity of rays.
`start_render`([camera_position, focal_point, ...])	Render the optical system geometry on a VTK window.

actors

surface actor.

Type:: Dictionary of surface name

add_rays(start, stop, surface_id=None, wavelengths=None, directions=None, length=None, point_size=1.0, show_rays=True, show_hits=True)

Draw rays from start to stop positions and highlight stop points.

If a stop position is NaN (indicating a miss), the ray is skipped by default. If ‘length’ and ‘directions’ are provided, rays with NaN stops are drawn starting from ‘start’ along ‘direction’ for ‘length’ units (without a hit dot).

Parameters:

start (ndarray) – (n, 3) array of starting coordinates (x, y, z).
stop (ndarray) – (n, 3) array of stopping coordinates (x, y, z).
surface_id (ndarray) – (n,) array of surface indices reached by each ray.
directions (ndarray, optional) – (n, 3) array of direction vectors. Required if plotting NaN rays with fixed length.
length (float, optional) – If provided, rays with NaN stop will be drawn with this length using the direction vector.
opacity (float, optional) – Transparency of the rays from 0.0 (invisible) to 1.0 (opaque). Default is 0.5.
point_size (float, optional) – Size of the hit points. Default is 1.0
show_rays (bool, optional) – Whether to show rays or not. Default is True.
show_hits (bool, optional) – Whether to show hits or not. Default is True.

get_screenshot(camera_position, filename=None, focal_point=None, view_up=(0, 0, 1), size=None, image_scale=1, orthographic=False, representation='surface', hide_surfaces=None, zoom=1.0, show=False, position_reference='telescope', position_shift=(0, 0, 0))

Render the scene off-screen and save it to a PNG file.

Coordinates for camera position, focal point, and view up should be provided in the telescope coordinate system. The method handles the transformation to the local coordinate system automatically.

Parameters:

camera_position (sequence of float) – The (x, y, z) coordinates of the camera position. The reference frame can be specified with the position_reference parameter.
filename (str, optional) – Path to save the resulting PNG file. If None, the screenshot is not saved.
focal_point (str or sequence of float, optional) – The point the camera is looking at. - If None (default): The camera looks at the center of the bounding box of all system actors. - If str: Looks for an optical surface with this name and targets its position. - If sequence: Uses the provided (x, y, z) coordinates (assumend to be local coordinates).
view_up (sequence of float) – The vector defining the “up” direction for the camera, default=(0, 0, 1).
size (tuple of int, optional) – The (width, height) of the rendered image in pixels. If None, uses the current window size.
image_scale (int) – Resolution multiplier (e.g., 2 doubles the pixel density), default=1.
orthographic (bool) – If True, uses parallel projection. If False, uses standard perspective projection. By default False.
representation ({'surface', 'wireframe', 'points'}) – The rendering style of the actors in the scene, default=’surface’.
hide_surfaces (list of str, optional) – A list of names of surfaces/actors to exclude from the render.
zoom (float) – Zoom factor applied when orthographic is True. - 1.0: Fits the object diagonal to the screen height. - > 1.0: Zooms in. - < 1.0: Zooms out. By default 1.0. Note: This parameter currently implies no effect if orthographic is False.
show (bool) – If True, displays the image using Matplotlib. Default is False.
position_reference – Reference system of the specified camera position, by default ‘telescope’. If does not starts with ‘t’, the camera position is assumed to be relative to the local reference system.

Returns:

RGB image array with shape (height, width, 3).

Return type:

numpy.ndarray

set_ray_opacity(value)

Set the opacity of rays.

Parameters:: value (float) – Ray opacity.

start_render(camera_position=None, focal_point=None, view_up=(0, 0, 1), orthographic=False)

Render the optical system geometry on a VTK window.

Parameters:

camera_position (tuple or list, optional) – (x, y, z) coordinates for the camera position.
focal_point (tuple, list, or str, optional) – If tuple/list: (x, y, z) coordinates to look at. If str: The name of the surface in self.os to look at. If None: Defaults to center of system.
view_up (tuple or list, optional) – (x, y, z) vector defining the “up” direction. Default is (0, 0, 1).
orthographic (bool, optional) – If True, start with a parallel projection. If False, start with a perspective projection. Default is False.

window_size: Window size in pixel.

wireframe: Whether to use wireframe representation by default.

iactsim.visualization.browse_images(image_lists=None, geom=None, cmaps=None, vmins=None, vmaxs=None, titles=None, plot_kwargs=None, prefix='event', plot_function=None, where=None)

An interactive widget to browse camera images or call a custom plotting function.

This function generates a Jupyter-compatible interactive UI with a slider and navigation buttons to step through camera events. It supports rendering either a single image stream, comparing multiple image streams side-by-side in synchronized subplots, or rendering custom figure logic.

If a plotting function is provided, it will be called with each item from the where iterable to generate a custom figure. Otherwise, the function will use camerashow to render images from the provided lists.

Parameters:

image_lists (array_like or list of array_like, optional) – A single list/array of images, or a list containing multiple lists of images to be plotted side-by-side. Required if plot_function is None.
geom (object, optional) – The camera geometry object required by the camerashow backend. Required if plot_function is None. cmaps : str or list of str, optional The colormap(s) to use. If a single string is provided alongside multiple image lists, the colormap is applied to all plots. Default is ‘viridis’.
vmins (float or list of float, optional) – The minimum data value(s) that correspond to the lower end of the colormap. If a single value is provided alongside multiple image lists, the value is applied to all plots. If None, it dynamically updates based on the current image minimum value. Default is None.
vmaxs (float or list of float, optional) – The maximum data value(s) that correspond to the upper end of the colormap. If a single value is provided alongside multiple image lists, the value is applied to all plots. If None, it dynamically updates based on the current image maximum value. Default is None.
titles (str or list of str, optional) – The title(s) to display above each subplot. The event index is automatically appended (e.g., “Title - Event 0”). If a single string is provided alongside multiple image lists, the title is applied to all plots. Defaults to None.
plot_kwargs (dict or list of dict, optional) – Additional keyword arguments (e.g., {‘show_axes’: True, ‘colorbar’: False}) to pass directly to the underlying camerashow function. If a single dictionary is passed, it applies to all subplots.
prefix (str, optional) – The prefix used for the filename when clicking the “Save” button. Default is “event”.
plot_function (callable, optional) – A custom function that takes a single argument (an item from where) and returns a matplotlib Figure. If provided, standard plotting is bypassed.
where (iterable, array_like, or boolean mask, optional) – If plot_function is provided, this is an iterable of items passed into it. If plot_function is None, this acts as a mask or index array to filter all image lists before plotting.

Raises:

RuntimeError – If the function is executed outside of an IPython/Jupyter notebook.
ValueError – If inputs are invalid or misaligned. If plot_function is provided without a corresponding where iterable. If image_lists and geom are not provided when plot_function is None. If the where mask filters out all images, resulting in an empty list. If the inner lists in image_lists have different lengths after filtering.

iactsim.visualization.camerashow(image, geom, ax=None, figsize=None, cmap='viridis', vmin=None, vmax=None, colorbar=True, show=False, rasterized=True, show_axes=False, interactive_tooltip=True)

Plots an image of the camera using true pixel positions and shapes, mapping a 1D array of pixel values to a colormap.

Parameters:

image (numpy.ndarray or cupy.ndarray) – A 1D or 2D array, with N elements, containing the values to plot for each pixel. It is assumed that the array index corresponds to the pixel ID (0 to N-1).
geom (CameraGeometry) – The camera geometry object containing pixel positions and shapes.
ax (matplotlib.axes.Axes, optional) – The axis on which to plot. If None, a new figure and axis are created.
figsize (tuple, optional) – The size of the figure to create if ax is None. Defaults to None.
cmap (str or matplotlib.colors.Colormap, optional) – The colormap to use for mapping the image values. Defaults to ‘viridis’.
vmin (float, optional) – The minimum data value that corresponds to the lower end of the colormap. If None, the minimum of the image array is used.
vmax (float, optional) – The maximum data value that corresponds to the upper end of the colormap. If None, the maximum of the image array is used.
colorbar (bool, optional) – If True, adds a colorbar to the figure. Defaults to True.
show (bool, optional) – If True, calls plt.show() at the end of the function. Defaults to False.
rasterized (bool, optional) – If True, rasterizes the patch collection when saving to vector formats to prevent artifacts. Defaults to True.
show_axes (bool, optional) – If True, displays the x and y axes with labels. Defaults to False.
interactive_tooltip (bool, optional) – If True, enables a hover tooltip showing the pixel ID and value. Defaults to True.

Returns:

ax (matplotlib.axes.Axes) – The axis containing the plot.
collection (matplotlib.collections.PatchCollection) – The generated patch collection (useful for updating data in animations).
cax (matplotlib.axes.Axes or None) – The axis containing the colorbar, or None if colorbar=False.

iactsim.visualization.histogram2d(vectors3d, bins, plane='xy', to_weight=None, dx=None, ax=None, scale=1., norm=None, range=None, update_this=None, log=False, vmin=None, vmax=None, cmap='viridis', interpolation='nearest', colorbar=True, cbar_label=None, title=None, xlabel=None, ylabel=None, **kwargs)

Generates and displays a 2D histogram of two components of a set of 3D vectors.

Parameters:

vectors3d (numpy.ndarray) – A NumPy array representing a set of 3D vectors. The first two columns are used as x and y coordinates for the histogram. The third column is ignored.
bins (int or array_like) – The number of bins or the bin edges (see numpy.histogram2d documentation for details).
plane (str) – String representation of the components to plot, e.g.: ‘xy’, ‘zy’, ‘zx’, etc.
to_weight (numpy.ndarray, optional) – Weights for each vector. If None, all vectors are weighted equally.
dx (float, optional) – Determines the range if range is not explicitly provided. Defines a square region around the data center with sides of length 2*dx.
ax (matplotlib.axes.Axes, optional) – An Axes object to plot on. If None, the current axes (plt.gca()) is used.
scale (float, optional) – Scaling factor applied to x and y coordinates.
norm (matplotlib.colors.Normalize, optional) – Normalization instance for histogram data (e.g., colors.LogNorm for logarithmic scaling).
range (sequence, optional) – A sequence of (min, max) pairs for each dimension, specifying the data range to be histogrammed.
update_this (numpy.ndarray, optional) – A 2D array (another histogram) to be added to the calculated histogram.
log (bool, optional) – If True, applies a log1p transformation (log(1 + x)) to the histogram counts.
vmin (float, optional) – Minimum value for colormap scaling.
vmax (float, optional) – Maximum value for colormap scaling.
cmap (str, optional) – The colormap to use.
interpolation (str, optional) – Interpolation method used by imshow.
colorbar (bool, optional) – Whether to add a colorbar.
cbar_label (str, optional) – Label for the colorbar.
title (str, optional) – Title of the plot.
xlabel (str, optional) – Label for the x-axis.
ylabel (str, optional) – Label for the y-axis.
**kwargs – Additional keyword arguments passed to numpy.histogram2d.

Returns:

H (numpy.ndarray) – The 2D histogram array.
im (matplotlib.image.AxesImage) – The image object returned by imshow.

Examples

>>> data = np.random.randn(1000, 3)
>>> H, im = histogram2d(data, bins=50, log=True, title="2D Histogram")
>>> plt.show()

>>> weights = np.random.rand(1000)
>>> H, im = histogram2d(data, bins=50, to_weight=weights, cbar_label="Average Weight")
>>> plt.show()

iactsim.visualization.scatter(vectors3d, colors_array=None, plane='xy', s=0.1, marker=None, ax=None, scale=1., cbar=True, **kwargs)

Creates a scatter plot of two components of a set of 3D vectors.

Parameters:

vectors3d (array_like) – A numpy.ndarray or list of 3D vectors. The shape should be (N, 3), where N is the number of vectors.
colors_array (array_like, optional) – An numpy.ndarray of color values for each point. Can be a list of color names, a list of RGB/RGBA tuples, or a 1D array of numerical values to be mapped to colors using a colormap.
plane (str) – String representation of the components to plot, e.g.: ‘xy’, ‘zy’, ‘zx’, etc.
s (float, optional) – The marker size in points**2 (default: 0.1).
marker (str, optional) – The marker style (default: None, which uses the default marker style from matplotlib). See matplotlib.markers for valid marker styles.
ax (matplotlib.axes.Axes, optional) – The axes on which to plot. If None, the current axes are used (plt.gca()).
scale (float, optional) – A scaling factor applied to the x and y coordinates (default: 1.).
cbar (bool, optional) – Whether to add a colorbar (default: True). The colorbar will only be added if colors_array is also provided and is a list or NumPy array.
**kwargs – Additional keyword arguments passed to matplotlib.pyplot.scatter. This allows for customization of the plot, such as setting the colormap (‘cmap’), edgecolors (‘edgecolors’), etc.

Returns:

cax – The axes of the colorbar if a colorbar is created; otherwise, None.

Return type:

matplotlib.axes.Axes or None

utils

Classes:

BenchmarkTimer()

A class to time and manage benchmark results organized in "sections" and "measurements".

Functions:

`convert_doxygen_to_numpy`(cuda_source, ...)	Converts Doxygen-style documentation within the given source code to NumPy-style docstrings.
`get_kernel`(module, kernel_name[, ...])	Get kernel wrapper.
`wrap_cupy_rawkernel`(raw_kernel, docstring)	Generates wrapper function for a CuPy RawKernel.

class iactsim.utils.BenchmarkTimer

A class to time and manage benchmark results organized in “sections” and “measurements”.

Example

from iactsim.utils import BenchmarkTimer
import random
import time

class Foo():
    def __init__(self):
    self.timer = BenchmarkTimer()
    self.timer.add_section('foo1')
    self.timer.add_section('foo2')

    def foo1(self):
    t0 = time.time()
    time.sleep(random.randint(0,50)/1000.)
    t1 = time.time()
    time.sleep(random.randint(0,5)/1000.)
    t2 = time.time()
    self.timer.add_entry('foo1', 'First', t1-t0)
    self.timer.add_entry('foo1', 'Second', t2-t1)

    def foo2(self):
    t0 = time.time()
    time.sleep(random.randint(0,30)/1000.)
    t1 = time.time()
    self.timer.add_entry('foo2', 'foo2', t1-t0)

foo = Foo()
for i in range(100):
    foo.foo1()
    foo.foo2()
foo.timer.print_results()

Methods:

`add_entry`(section_name, measure_name, ...)	Adds a timing entry for a specific measure within a section.
`add_section`(section_name)	Adds a new section (e.g., a method name) to the results.
`clear`()	Resets the timer, keeping sections and measures, but clearing samples.
`get_results`()	Returns the raw results dictionary.
`print_results`([title, show_total, ...])	Prints the timings, handling both notebook and console output.

add_entry(section_name, measure_name, elapsed_time)

Adds a timing entry for a specific measure within a section.

Parameters:

section_name (str) – The name of the section.
measure_name (str) – The name of the measurement within the section.
elapsed_time (float) – The elapsed time in seconds.

add_section(section_name)

Adds a new section (e.g., a method name) to the results.

Parameters:: section_name (str) – The name of the section to add.

clear(): Resets the timer, keeping sections and measures, but clearing samples.

get_results()

Returns the raw results dictionary.

Returns:: The results dictionary, structured as: {section_name: {measure_name: [time1, time2, …]}}
Return type:: dict

print_results(title=None, show_total=True, return_str=False, tablefmt='grid')

Prints the timings, handling both notebook and console output.

Parameters:

title (str, optional) – An optional title to display above the table.
show_total (bool, optional) – Add a last row with the sum of all sections.

iactsim.utils.convert_doxygen_to_numpy(cuda_source, function_name)

Converts Doxygen-style documentation within the given source code to NumPy-style docstrings.

Parameters:

cuda_source (str) – The source code.
function_name (str) – The name of the function.

Returns:

docstring: str: The NumPy-style docstring or None if not found.

iactsim.utils.get_kernel(module, kernel_name, max_shared_memory_limit=False)

Get kernel wrapper.

Parameters:

module (cupy.RawModule) – A CuPy rawModule
kernel_name (str) – Name of the kernel to retrieve and wrap.

Returns:

Wrapper to the RawKernel with a NumPy-style docstring.

iactsim.utils.wrap_cupy_rawkernel(raw_kernel, docstring)

Generates wrapper function for a CuPy RawKernel. The wrapper allows you to provide a custom docstring.

Parameters:

raw_kernel (cupy.RawKernel) – The cupy.RawKernel object to wrap.
docstring (str) – A custom docstring for the wrapped kernel.

Returns:

A Python function that wraps the CuPy RawKernel.

models

models.astri

Classes:

`AstriCherenkovCamera`()	ASTRI Cherenkov camera class.
`AstriOpticalSystem`()	ASTRI optical system definition (dual-mirror Schwarzschild-Couder).
`AstriTelescope`([optical_system, camera, ...])	ASTRI telescope.

class iactsim.models.astri.AstriCherenkovCamera

ASTRI Cherenkov camera class.

Methods:

`acquire_dark_pedestal`(n_frame)	Acquire pulse-height distribution with an external trigger and the closed lids background.
`acquire_pedestal`(n_frame)	Acquire pulse-height distribution with an external trigger and the current background.
`acquire_phd`(n_frame[, background, laser_width])	Acquire pulse-height distribution with pulsed flash light.
`acquire_stairs`(start, stop, step[, ...])	Acquire staircase curves (pixel dark trigger rate as a function of threshold).
`acquire_variance`(n_sample_hg[, n_sample_lg, ...])	Acquire variance data.
`configure`(config)	Configure the camera with a yaml configuration file or a dictionary.
`post_sampling_action`()	Optional action that is performed right after the sampling action.
`sampling_action`()	Perform peak detection and pixels trigger time measurement.
`threshold_scan`(start, stop, step[, ...])	Measure the camera trigger rate as a function of the trigger threshold.
`trigger_action`()	Generate a camera trigger.

acquire_dark_pedestal(n_frame)

Acquire pulse-height distribution with an external trigger and the closed lids background.

Parameters:: n_frame (int) – number of frame to be acquired.

acquire_pedestal(n_frame)

Acquire pulse-height distribution with an external trigger and the current background.

Parameters:: n_frame (int) – number of frame to be acquired.

acquire_phd(n_frame, background=None, laser_width=10.)

Acquire pulse-height distribution with pulsed flash light.

Parameters:

n_frame (int) – number of frame to be acquired.
laser_width (int) – Duration of the laser pulse.

acquire_stairs(start, stop, step, integration_time=0.001, window_extent=1024.)

Acquire staircase curves (pixel dark trigger rate as a function of threshold).

Parameters:

start (float) – Start threshold value.
stop (float) – Stop threshold value.
step (float) – Threshold step.
integration_time (float, optional) – Integration time (in seconds), by default 0.001 s
window_extent (float, optional) – Extent in ns of the time window where to count triggers, by default 1024 ns.

Returns:

Thresholds and corresponding trigger rate per pixel.

Return type:

(numpy.ndarray, numpy.ndarray)

acquire_variance(n_sample_hg, n_sample_lg=None, source=None, background=None)

Acquire variance data.

Parameters:

n_sample_hg (int) – Number of HG sample to be acquired.
n_sample_lg (int, optional) – Number of LG sample to be acquired. If None use HG number of sample.
source (int, optional) – Source to be added to the background. If it is not None, the variance is measured at tmin+0.9*(tmax-tmin), where tmin and tmax are the minimum and maximum arrival time of the source. The source arrival times should be uniformly distributed between tmin and tmax. At each variance sample the source arrival times are randomized again, but the number of discharge per pixel/microcell is the same.
background (int, optional) – If not None, temporarly replace the background attribute. The old attribute is restored.

Returns:

High gain and low gain variance arrays.

Return type:

tuple(cp.ndarray, cp.ndarray)

Notes

In order to simulate microcells with non-diffused background (e.g. starts), a naive way is to use the output source of the ray-tracing (get_camera_input=True) and randomize the arrival time at each variance sample. This is the default behaviour if you pass source to this method. But remember to generate the source photons with uniform (and large-spreaded) arrival times:

..code-block:: python

source = sources.Source(astri_tel) source.arrival_times.type = ‘uniform’ source.arrival_times.tmin = 0 source.arrival_times.tmax = 2048

Although the timing is handle properly, the microcell IDs are not. A fix for this is planned in the future.

configure(config)

Configure the camera with a yaml configuration file or a dictionary.

Parameters:: config (str, path-like, or dict) – Path to the configuration file (str or pathlib.Path), or a dictionary containing the configuration.
Return type:: None

post_sampling_action(): Optional action that is performed right after the sampling action. This method is called only if a trigger condition is met or if the camera trigger is disabled.

sampling_action(): Perform peak detection and pixels trigger time measurement.

threshold_scan(start, stop, step, window_extent=1024., max_duration=1e-3, maximum_count=None, background=None)

Measure the camera trigger rate as a function of the trigger threshold.

Parameters:

start (float) – Start threshold value.
stop (float) – Stop threshold value.
step (float) – Threshold step.
window_extent (float, optional) – Extent in ns of the time window where to count triggers, by default 1024 ns.
max_duration (float, optional) – Integration time (in seconds) for each threshold, by default 1e-3 s.
maximum_count (int, optional) – Stop when at least maximum_count triggers have been found at a each threshold, useful to speed-up the procedure at lower thresholds. By default None.

Returns:

Thresholds and corresponding rate, rate error and integration time. Integration times can be different for each threshold if a maximum_count is provided.

Return type:

trigger_action(): Generate a camera trigger.

class iactsim.models.astri.AstriOpticalSystem

ASTRI optical system definition (dual-mirror Schwarzschild-Couder).

This class defines the optical geometry and the main shadowing elements of the mechanical structure of the ASTRI telescope.

Coordinate System

Origin (0,0,0): vertex of the primary mirror (M1).
z-axis: optical axis, concave surfaces must have c>0.

Parametrization

The system is divided into independent clusters that can be moved along the optical axis (Z) without affecting other components:

M1: - Static at Z=0. - Can be segmented (hexagonal segments) or monolithic.
Secondary mirror (M2): - Controlled by m2_axial_position. - Includes the M2 mirror and its mechanical baffles.
Camera: - Controlled by fp_axial_position (focal plane vertex); - Includes the focal plane, the camera window, the camera body, and the central tube; - Moving the FP automatically moves the window and sensors;

Direct Surface Access

Apart from the main parameters that control the M1, M2, and Camera clusters, the properties of each specific surface can be modified via direct access (e.g., self['M2'].position =).

Warning

When modifying surfaces directly, no overlap or collision checks are performed.

When to call rebuild_structure() manually: If you modify a parameter that affects dependent geometry (e.g., changing M2 position should change the M2 Baffle position), you can call self.rebuild_structure() manually after your changes to apply them to the rest of the system.

The auto-reorganization of the surfaces is not completely supported, please check your geometry with visualization.VTKOpticalSystem. A lot of surfaces are destroyed and recreated from scratch whenever rebuild_structure() is called. Any custom properties applied directly will be lost. So, it would be better to assign non-geometry properties after calling rebuild_structure().

See also

iactsim.optics.OpticalSystem

Methods:

`build_m1_segments`()	Builds the 18 hexagonal segments of M1 using nominal coordinates.
`configure`(config)	Configure the optical system.
`rebuild_structure`()	Full rebuild of all component positions based on current independent parameters.
`remove_m1_segments`()	Removes M1 segments and restores the monolithic M1 mirror.
`remove_window_layers`()	Removes the window layers and restores the dummy window.
`set_camera_window_parameters`(radius, ...[, ...])	Set the camera window parameters and build the window layers.

Attributes:

`camera_body_axial_position`	Axial position of the camera body center.
`camera_body_size`	Cylindrical camera body dimensions [radius, height].
`camera_window_parameters`	Dictionary of camera window parameters.
`default_m1_a`
`default_m2_a`
`fp_axial_position`	Axial position of the focal plane vertex.
`m2_axial_position`	Axial position of the M2 mirror vertex.

build_m1_segments(): Builds the 18 hexagonal segments of M1 using nominal coordinates. Each segment inherits optical properties from the monolithic M1, which is then removed.

property camera_body_axial_position: Axial position of the camera body center.

property camera_body_size: Cylindrical camera body dimensions [radius, height].

property camera_window_parameters: Dict[str, float] | None: Dictionary of camera window parameters. Read-only property. Use set_camera_window_parameters to modify.

configure(config)

Configure the optical system.

Return type:: None

default_m1_a = array([-0.00000000e+00, -9.61059434e-13, 5.65500725e-20, -6.77984630e-27, -3.89587887e-33, -5.28038180e-40, 2.99106074e-47, 4.39153059e-53, 6.17433202e-60, -2.73586546e-66])

default_m2_a = array([-0.00000000e+00, -1.62075903e-11, 2.89584356e-17, -8.63371219e-24, -3.34855806e-30, 1.03361002e-36, 6.73525366e-43, 3.06547119e-49, -3.17161236e-55, 3.71183104e-62])

property fp_axial_position: Axial position of the focal plane vertex. Changing this moves the camera sensitive surface, window, and central tube.

property m2_axial_position: Axial position of the M2 mirror vertex. Changing this moves M2 and its baffles.

rebuild_structure(): Full rebuild of all component positions based on current independent parameters.

remove_m1_segments(): Removes M1 segments and restores the monolithic M1 mirror.

remove_window_layers()

Removes the window layers and restores the dummy window.

Return type:: None

set_camera_window_parameters(radius, sipm_distance, thickness, separation, top_camera_body_distance, layer_1_as_cylinder=True, layer_2_as_cylinder=True, layer_3_as_cylinder=True)

Set the camera window parameters and build the window layers.

Parameters:

radius (float) – Radius of the window layers.
sipm_distance (float) – Distance from the SiPM surface to the window.
thickness (float) – Thickness of each window layer.
separation (float) – Separation between window layers.
top_camera_body_distance (float) – Distance between the top window layer and the top of the camera body.

Return type: