Python API

The phepex package: numpy kernel wrappers, the C++ waveform generator, and the ctapipe-integrated FastFlashCamExtractor. The package overview below is rendered from the package docstring.

Package overview

phepex – photo-electron pulse extraction.

C++-accelerated kernels for extracting charge and timing from digitised PMT/SiPM (e.g. Cherenkov telescopes or Water Cherenkov Detectors) waveforms, plus a fast waveform generator for testing.

import phepex depends only on numpy and the compiled extension; the ctapipe-based phepex.extractor is a separate submodule imported on demand.

phepex.deconvolve(waveforms, baselines, upsampling, pole_zero)[source]

Pole-zero deconvolution + upsampling; drop-in for ctapipe’s deconvolve.

waveforms (n_channels, n_pix, n_samples); baselines scalar or per-pixel; upsampling >= 1. Returns float32 (n_channels, n_pix, n_samples*upsampling).

phepex.pos_soft_clip(waveforms, scale, sample_lo=0, sample_hi=0)[source]

Positive soft clip max(clip(waveforms/scale), 0) over [sample_lo, sample_hi).

(0, 0) means the full trace. The soft clip already bounds the result to (-1, 1), so only negatives are clamped (to 0). Equivalent to ctapipe FlashCamExtractor.clip(waveforms / scale).

phepex.neighbor_peak_indices(waveforms, neighbors, local_weight, broken_pixels, sample_lo=0, sample_hi=0)[source]

Per-pixel peak sample index of the neighbour-summed waveform.

Equivalent to ctapipe’s neighbor_average_maximum. neighbors is a scipy CSR matrix (geometry.neighbor_matrix_sparse); its indices/indptr are cast to int32. Returns int64 (n_channels, n_pix).

phepex.extract_around_peak(waveforms, peak_index, width, shift, sampling_rate_ghz)[source]

Window integration + weighted peak time; ctapipe’s extract_around_peak.

Returns (charge, peak_time) float32; peak_time in ns.

phepex.adaptive_centroid(waveforms, peak_index, rel_descend_limit)[source]

Leading-edge centroid in sample units; ctapipe’s adaptive_centroid.

float32 (n_channels, n_pix).

phepex.deconvolve_valid_range(upsampling, n_samples, pole_zero)[source]

Trustworthy (non-edge) output-sample range (lo, hi) of deconvolve.

Delegates to the C++ deconvolve_valid_range so the edge-trim rule has a single source of truth (the same one the C++/test path uses).

Kernels (numpy wrappers)

Thin numpy-friendly wrappers over the compiled phepex._core kernels; these depend only on numpy (no ctapipe).

NumPy-friendly wrappers over the compiled phepex._core kernels.

These depend only on numpy and the C++ extension (no ctapipe), so import phepex stays lightweight. Each mirrors the corresponding ctapipe FlashCamExtractor step.

phepex.kernels.deconvolve(waveforms, baselines, upsampling, pole_zero)[source]

Pole-zero deconvolution + upsampling; drop-in for ctapipe’s deconvolve.

waveforms (n_channels, n_pix, n_samples); baselines scalar or per-pixel; upsampling >= 1. Returns float32 (n_channels, n_pix, n_samples*upsampling).

phepex.kernels.pos_soft_clip(waveforms, scale, sample_lo=0, sample_hi=0)[source]

Positive soft clip max(clip(waveforms/scale), 0) over [sample_lo, sample_hi).

(0, 0) means the full trace. The soft clip already bounds the result to (-1, 1), so only negatives are clamped (to 0). Equivalent to ctapipe FlashCamExtractor.clip(waveforms / scale).

phepex.kernels.neighbor_peak_indices(waveforms, neighbors, local_weight, broken_pixels, sample_lo=0, sample_hi=0)[source]

Per-pixel peak sample index of the neighbour-summed waveform.

Equivalent to ctapipe’s neighbor_average_maximum. neighbors is a scipy CSR matrix (geometry.neighbor_matrix_sparse); its indices/indptr are cast to int32. Returns int64 (n_channels, n_pix).

phepex.kernels.extract_around_peak(waveforms, peak_index, width, shift, sampling_rate_ghz)[source]

Window integration + weighted peak time; ctapipe’s extract_around_peak.

Returns (charge, peak_time) float32; peak_time in ns.

phepex.kernels.adaptive_centroid(waveforms, peak_index, rel_descend_limit)[source]

Leading-edge centroid in sample units; ctapipe’s adaptive_centroid.

float32 (n_channels, n_pix).

phepex.kernels.deconvolve_valid_range(upsampling, n_samples, pole_zero)[source]

Trustworthy (non-edge) output-sample range (lo, hi) of deconvolve.

Delegates to the C++ deconvolve_valid_range so the edge-trim rule has a single source of truth (the same one the C++/test path uses).

Waveform generator

The generator is implemented in C++ and exported at the package top level.

phepex.generate_waveforms(charge: ndarray[dtype=float64, shape=(*, *), order='C', writable=False], time_ns: ndarray[dtype=float64, shape=(*, *), order='C', writable=False], reference_pulse: ndarray[dtype=float64, shape=(*), order='C', writable=False], ref_sample_width_ns: float, sample_width_ns: float, n_samples: int, upsampling: int = 10, nsb_rate_ghz: float = 0.0, seed: int = 0) → numpy.ndarray[dtype=float32]

Synthesize (n_events, n_pixels, n_samples) float32 waveforms from per-pixel (charge, peak_time): a physically-placed signal deposit plus Poisson NSB. Matches ctapipe WaveformModel for deposits inside the readout window, but is physically correct at the edges (floor-snapped deposit time, and pulses centred just outside the window still contribute their in-window tail rather than being dropped as WaveformModel does).

ctapipe extractor

FastFlashCamExtractor is a drop-in subclass of ctapipe’s FlashCamExtractor that runs the numeric pipeline (deconvolution, clip, peak search, integration, leading-edge timing) through the phepex C++ kernels. Importing it requires ctapipe (pip install .[bench]).

class phepex.extractor.FastFlashCamExtractor(*args: t.Any, **kwargs: t.Any)[source]

Bases: FlashCamExtractor

FlashCamExtractor with the numeric pipeline done in C++ (phepex kernels).

__call__(waveforms, tel_id, selected_gain_channel, broken_pixels) → DL1CameraContainer[source]

Call the relevant functions to fully extract the charge and time for the particular extractor.

Parameters:

  • waveforms (ndarray) – Waveforms stored in a numpy array of shape (n_channels, n_pix, n_samples).

  • tel_id (int) – The telescope id. Used to obtain to correct traitlet configuration and instrument properties

  • selected_gain_channel (ndarray) – The channel selected in the gain selection, per pixel. Required in some cases to calculate the correct correction for the charge extraction.

  • broken_pixels (ndarray) – Mask of broken pixels used for certain ImageExtractor types. Shape: (n_channels, n_pix)

Returns:

extracted images and validity flags

Return type:

DL1CameraContainer