Camera

camera_efficiency

The camera_efficiency module calculates telescope throughput and NSB rates from validated model tables. A TelescopeModel and a few physical parameters (zenith angle, etc.) are required inputs.

Camera efficiency simulations and analysis.

class camera.camera_efficiency.CameraEfficiency(label, config_data, efficiency_type, telescope_model=None, site_model=None, *, context=None)

Camera efficiency simulations and analysis.

Parameters:

label: str

Instance label, optional.

config_data: dict.

Dict containing the configurable parameters.

efficiency_type: str

The type of efficiency to simulate (e.g., ‘Shower’, ‘Muon’, or ‘NSB’).

telescope_model: TelescopeModel, optional

Reuse an initialized telescope model.

site_model: SiteModel, optional

Reuse an initialized site model.

analyze(export=True, force=False)

Analyze camera efficiency output file and store the results in _results.

Parameters:

export: bool

If True, results will be exported to a file automatically. Alternatively, export_results function can be used.

force: bool

If True, existing results files will be removed and analysis will be done again.

calc_camera_efficiency()

Calculate the camera nominal efficiency including gaps (as defined in B-TEL-1170).

Returns:

cam_efficiency: float

Wavelength-averaged camera efficiency

calc_nsb_rate(wavelength_range=(<Quantity 300. nm>, <Quantity 650. nm>))

Calculate the NSB rate.

CTAO reference wavelength range is 300-650 nm.

Parameters:

wavelength_range: tuple

Wavelength range used for the NSB rate calculation (default: (300 nm, 650 nm)).

Returns:

nsb_rate_provided_spectrum: float

NSB pixel rate in p.e./ns for the provided NSB spectrum

nsb_rate_ref_conditions: float

NSB pixel rate in p.e./ns for reference conditions (https://jama.cta-observatory.org/perspective.req#/items/26694?projectId=11)

calc_partial_efficiency(lambda_min=200.0, lambda_max=290.0)

Compare efficiency in a given wavelength range with total efficiency.

Parameters:

lambda_min: float

Minimum wavelength in nm.

lambda_max: float

Maximum wavelength in nm.

Returns:

Float

Fraction of light in the given wavelength range compared to total efficiency.

calc_reflectivity()

Calculate the Cherenkov spectrum weighted reflectivity in the range 300-550 nm.

Returns:

Float

Cherenkov spectrum weighted reflectivity (300-550 nm)

calc_tel_efficiency()

Calculate the telescope total efficiency including gaps (as defined in A-PERF-2020).

Returns:

tel_efficiency: float

Telescope efficiency

calc_tot_efficiency(tel_efficiency)

Calculate the telescope total efficiency including gaps (as defined in A-PERF-2020).

Parameters:

tel_efficiency: float

The telescope efficiency as calculated by calc_tel_efficiency()

Returns:

Float

Telescope total efficiency including gaps

dump_nsb_pixel_rate()

Write NSB pixel rate parameter file.

export_results()

Export results to a ecsv file.

get_nsb_pixel_rate(reference_conditions=False)

Return the expected NSB pixel rate for each camera pixel.

This is an approximation because the calculator evaluates the on-axis pixel only.

Returns:

list

Expected NSB pixel rate in p.e./ns for the provided NSB spectrum.

plot_efficiency(save_fig=False)

Plot efficiency vs wavelength.

Parameters:

save_fig: bool

If True, the figure will be saved to a file.

Returns:

fig

The figure instance of pyplot

results_summary()

Fill a dictionary with summary of the results.

Include a header for the zenith/azimuth settings and the NSB spectrum file which was used. The summary includes the various CTAO requirements and the final expected NSB pixel rate.

Returns:

dict

Summary of the results.

simulate()

Calculate camera efficiency using the in-process ECSV calculator.

camera_efficiency_calculator

Calculate camera efficiency from validated model tables.

class simtools.camera.camera_efficiency_calculator.CameraEfficiencyCalculator(telescope_model, site_model, zenith_angle=0.0, x_max=300.0, nsb_spectrum=None, skip_correction_to_nsb_spectrum=False)

Compute the optical and NSB efficiency subset used by simtools.

Parameters:

telescope_modelTelescopeModel

Telescope model containing the optical inputs.

site_modelSiteModel

Site model containing atmosphere and NSB inputs.

zenith_anglefloat

Zenith angle in degrees.

x_maxfloat

Shower maximum in g/cm2.

nsb_spectrumstr or pathlib.Path, optional

Optional NSB spectrum overriding the site model spectrum.

skip_correction_to_nsb_spectrumbool

Skip the site and altitude correction applied to the reference NSB.

calculate()

Return wavelength results using the secant airmass approximation.

The approximation is defined for zenith angles from 0 degrees inclusive to 90 degrees exclusive. It is intended for moderate zenith angles; accuracy degrades near the horizon.

Raises:

ValueError

If the zenith angle is non-finite or outside [0, 90) degrees.

camera_efficiency_workflow

Run and export the standard camera-efficiency calculations.

simtools.camera.camera_efficiency_workflow.run_camera_efficiency(config, output_directory, label=None, telescope_model=None, site_model=None, context=None)

Run Shower, NSB and Muon camera-efficiency calculations.

Parameters:

configdict

Application configuration containing model, telescope and pointing settings.

output_directorypathlib.Path

Directory for the combined YAML summary.

labelstr, optional

Log label for this calculation.

telescope_model, site_modelobject, optional

Initialized models to reuse; both are initialized when either is omitted.

contextRunContext, optional

Run context passed to the models and calculators.

Returns:

dict

Combined summary, summary path and the generated result and plot paths.

Single photon-electron spectral analysis

single_photon_electron_spectrum

Single photon electron spectral analysis.

class camera.single_photon_electron_spectrum.SinglePhotonElectronSpectrum(args_dict, *, context=None)

Single photon electron spectral analysis.

Parameters:

args_dict: dict

Dictionary with input arguments.

afterpulse_fit_function(fix_k)

Afterpulse fit function: exponential decay with linear term in the exponent.

Starting values and bounds are set for the other parameters using values typical for LSTN-design. Allows to fix the K parameter.

Parameters:

fix_Kfloat

Fixed value for K parameter.

Returns:

function

Exponential decay function with linear term in the exponent.

derive_single_pe_spectrum()

Derive single photon electron spectrum.

fit_afterpulse_spectrum()

Fit afterpulse spectrum with a exponential decay function.

Assume input to be in ecsv format with columns ‘amplitude’, ‘frequency (afterpulsing)’, and ‘frequency stdev (afterpulsing)’.

Returns:

astro.Table

Table with fitted afterpulse spectrum data.

write_single_pe_spectrum()

Write single photon electron spectrum plus metadata to disk.

Write the generated model-parameter ECSV and its metadata.

Trace analysis

trace_analysis

Trace analysis.

camera.trace_analysis.calculate_pedestals(trace, start=None, end=None, half_width=2, offset=16)

Calculate pedestal per pixel.

If start/end are provided, uses fixed window. Otherwise, computes pedestal window dynamically based on detected peak position.

Parameters:

tracearray-like

Trace, shape (n_pixels, n_samples) or (1, n_pixels, n_samples).

startint, optional

Start index for fixed window. If None, uses dynamic windowing.

endint, optional

End index for fixed window.

half_widthint, optional

Half-width for dynamic pedestal window. Default is 2.

offsetint, optional

Offset from peak for dynamic pedestal window. Default is 16.

Returns:

np.ndarray

Mean pedestal value per pixel.

camera.trace_analysis.compute_integration_window(peak_idx, n_samp, half_width, mode, offset=None)

Compute integration window bounds for signal or pedestal modes.

Parameters:

peak_idxint

Index of the peak in the waveform.

n_sampint

Total number of samples in the waveform.

half_widthint

Half-width of the integration window.

modestr

Either “signal” or “pedestal”.

offsetint, optional

Offset for pedestal window from peak. Default is 16.

Returns:

tuple of int

Window bounds (start, end) for integration [start:end).

camera.trace_analysis.get_adc_samples_per_gain(adc_samples, low_gain=False)

Get ADC samples for low gain channel if specified.

Parameters:

adc_samplesarray-like

ADC samples array, shape (n_gains, n_pixels, n_samples) or (1, n_pixels, n_samples). where n_gains is typically 2 for dual-gain readout.

low_gainbool

If True, return low gain channel samples.

Returns:

np.ndarray

ADC samples for the specified gain channel (all pixels).

camera.trace_analysis.get_time_axis(time_slice, n_samples)

Generate a time axis from the sampling period.

Parameters:

time_sliceastropy.units.Quantity

Length of one sampling time slice (e.g., ns).

n_samplesint

Number of samples.

Returns:

np.ndarray

Time axis array.

camera.trace_analysis.get_trace_data(adc_samples)

Prepare gain-selected samples, pedestals, and integrated signal values.

Parameters:

adc_samplesarray-like

ADC samples with shape (n_gains, n_pixels, n_samples) or (n_pixels, n_samples).

Returns:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Gain-selected ADC samples, pedestal values per pixel, and integrated pedestal-subtracted signal values per pixel.

camera.trace_analysis.trace_integration(trace, pedestals, window)

Integrate traces over specific window.

Parameters:

tracearray-like

Trace, shape (n_pixels, n_samples) or (1, n_pixels, n_samples).

pedestalsarray-like or None

Pedestal values per pixel. If None, pedestals are calculated.

windowtuple of int

Integration window (start, end) indices.

Returns:

np.ndarray

Integrated trace values per pixel.

camera.trace_analysis.trace_maxima(trace, sum_threshold)

Compute trace maxima sample per pixel from waveform matrix.

Parameters:

tracenumpy.ndarray

Trace array of shape (n_pix, n_samples) (or (1, n_pix, n_samples)).

sum_thresholdfloat

Minimum sum over samples for a pixel to be considered.

Returns:

tuple[numpy.ndarray | None, numpy.ndarray | None, int]

(peak_samples, pix_ids, found_count) where peak_samples are the selected peak indices per considered pixel, pix_ids are the pixel indices that passed sum_threshold, and found_count is the number of pixels with at least one detected peak. Returns (None, None, 0) if no pixels passed the threshold.

camera.trace_analysis.trace_maximum(trace)

Detect trace maximum.

Parameters:

tracenumpy.ndarray

One-dimensional trace for a single pixel.

Returns:

numpy.ndarray

Array of integer indices of detected peaks (possibly empty).