lsurf.detectors.Detector

class lsurf.detectors.Detector(name='Detector')

Abstract base class for all detectors.

A detector records rays that pass through its detection volume, capturing their positions, directions, timing, and other properties.

Parameters:

name (str, optional) – Detector name for identification. Default is “Detector”.

name

Detector identifier.

Type:

str

events

Recorded detection events.

Type:

list of DetectionEvent

Notes

Derived classes must implement the detect() method which tests rays against the detector geometry and records detection events.

The base class provides common analysis methods for processing the recorded events.

Examples

Creating a custom detector:

>>> class MyDetector(Detector):
...     def __init__(self, position, radius, name="MyDetector"):
...         super().__init__(name)
...         self.position = np.array(position)
...         self.radius = radius
...
...     def detect(self, rays, current_time=0.0):
...         events = []
...         # ... detection logic ...
...         return events

__init__(name='Detector')

Initialize detector.

Parameters:

name (str, optional) – Detector name for identification. Default is “Detector”.

Methods

__init__([name])	Initialize detector.
clear()	Clear all recorded events.
detect(rays[, current_time])	Check which rays intersect this detector and record events.
get_arrival_angles(reference_direction)	Get angles between ray directions and reference direction.
get_arrival_times()	Get array of all arrival times.
get_intensities()	Get array of all detected intensities.
get_positions()	Get array of all detection positions.
get_total_intensity()	Get sum of all detected intensities.
get_wavelengths()	Get array of all detected wavelengths.

__init__(name='Detector')

Initialize detector.

Parameters:

name (str, optional) – Detector name for identification. Default is “Detector”.

abstractmethod detect(rays, current_time=0.0)

Check which rays intersect this detector and record events.

Parameters:

• rays (RayBatch) – Ray batch to test for detection.

• current_time (float, optional) – Current simulation time for reference. Default is 0.0.

Returns:

List of newly detected events.

Return type:

list of DetectionEvent

Notes

Implementations should: - Only test active rays (rays.active == True) - Create DetectionEvent for each detected ray - Append events to self.events - Return the list of newly created events

clear()

Clear all recorded events.

Resets the detector to its initial state with no recorded events.

get_arrival_times()

Get array of all arrival times.

Returns:

times – Arrival times in seconds for all detected rays.

Return type:

ndarray, shape (N,)

Examples

>>> times = detector.get_arrival_times()
>>> print(f"Mean arrival time: {times.mean():.3e} s")

get_arrival_angles(reference_direction)

Get angles between ray directions and reference direction.

Parameters:

reference_direction (ndarray, shape (3,)) – Reference vector for angle calculation.

Returns:

angles – Angles in radians between each detected ray’s direction and the reference direction.

Return type:

ndarray, shape (N,)

Examples

>>> angles = detector.get_arrival_angles(np.array([0, 0, 1]))
>>> print(f"Mean angle: {np.degrees(angles.mean()):.1f} degrees")

get_intensities()

Get array of all detected intensities.

Returns:

intensities – Intensity values for all detected rays.

Return type:

ndarray, shape (N,)

get_wavelengths()

Get array of all detected wavelengths.

Returns:

wavelengths – Wavelengths in meters for all detected rays.

Return type:

ndarray, shape (N,)

get_positions()

Get array of all detection positions.

Returns:

positions – 3D positions where rays were detected.

Return type:

ndarray, shape (N, 3)

get_total_intensity()

Get sum of all detected intensities.

Returns:

Total detected intensity (power).

Return type:

float

__len__()

Return number of detection events.

__repr__()

Return string representation.