Production Configuration

Modules provide functionality to configure a simulation production. This includes the derivation of energy, viewcone radius, and core scatter ranges and the calculation of the number of events to be simulated given a pre-determined metric.

calculate_statistical_uncertainties_grid_point

Evaluate statistical uncertainties from DL2 MC event files.

class production_configuration.calculate_statistical_uncertainties_grid_point.StatisticalUncertaintyEvaluator(file_path: str, metrics: dict[str, float], grid_point: tuple[float, float, float, float, float] | None = None)

Evaluate statistical uncertainties for a metric at a point in the observational parameter grid.

Parameters:

file_pathstr

Path to the DL2 MC event file.

metricsdict

Dictionary of metrics to evaluate.

grid_pointtuple, optional

Grid point (energy, azimuth, zenith, NSB, offset).

calculate_energy_estimate()

Calculate the uncertainties in energy estimation.

Returns:

float

The calculated uncertainty for energy estimation.

calculate_energy_threshold(requested_eff_area_fraction=0.1)

Calculate the energy threshold where the effective area exceeds 10% of its maximum value.

Returns:

float

Energy threshold value.

calculate_max_error_for_effective_area()

Calculate the maximum relative uncertainty for effective area within the validity range.

Returns:

max_errorfloat

Maximum relative error.

calculate_metrics()

Calculate all defined metrics as specified in self.metrics and store results.

calculate_overall_metric(metric='average')

Calculate an overall metric for the statistical uncertainties.

Parameters:

metricstr

The metric to calculate (‘average’, ‘maximum’).

Returns:

float

The overall metric value.

calculate_uncertainty_effective_area()

Calculate the uncertainties on the effective collection area.

Returns:

dict

Dictionary with uncertainties for the file.

compute_efficiency_and_uncertainties(reconstructed_event_counts, simulated_event_counts)

Compute reconstructed event efficiency and its uncertainty assuming binomial distribution.

Parameters:

reconstructed_event_countsarray with units

Histogram counts of reconstructed events.

simulated_event_countsarray with units

Histogram counts of simulated events.

Returns:

efficienciesarray

Array of calculated efficiencies.

relative_uncertaintiesarray

Array of relative uncertainties.

compute_reconstructed_event_histogram(event_energies_reco, bin_edges)

Compute histogram of events as function of reconstructed energy.

Parameters:

event_energies_recoarray

Array of reconstructed energy per event.

bin_edgesarray

Array of energy bin edges.

Returns:

reconstructed_event_histogramarray

Histogram of reconstructed events.

create_energy_bin_edges()

Create unique energy bin edges.

Returns:

bin_edgesarray

Array of unique energy bin edges.

load_data_from_file(file_path)

Load data from the DL2 MC event file and return dictionaries with units.

Returns:

dict

Dictionary containing data from the DL2 MC event file with units.

derive_corsika_limits

Calculate CORSIKA thresholds for energy, radial distance, and viewcone.

class production_configuration.derive_corsika_limits.LimitCalculator(event_data_file, array_name=None, telescope_list=None)

Compute limits for CORSIKA configuration for energy, radial distance, and viewcone.

Event data is read from the reduced MC event data file.

Parameters:

event_data_filestr

Path to the event-data file.

array_namestr, optional

Name of the telescope array configuration (default is None).

telescope_listlist, optional

List of telescope IDs to filter the events (default is None).

compute_limits(loss_fraction)

Compute the limits for energy, radial distance, and viewcone.

Parameters:

loss_fractionfloat

Fraction of events to be lost.

Returns:

dict

Dictionary containing the computed limits.

compute_lower_energy_limit(loss_fraction)

Compute the lower energy limit in TeV based on the event loss fraction.

Parameters:

loss_fractionfloat

Fraction of events to be lost.

Returns:

astropy.units.Quantity

Lower energy limit.

compute_upper_radius_limit(loss_fraction)

Compute the upper radial distance based on the event loss fraction.

Parameters:

loss_fractionfloat

Fraction of events to be lost.

Returns:

astropy.units.Quantity

Upper radial distance in m.

compute_viewcone(loss_fraction)

Compute the viewcone based on the event loss fraction.

The shower IDs of triggered events are used to create a mask for the azimuth and altitude of the triggered events. A mapping is created between the triggered events and the simulated events using the shower IDs.

Parameters:

loss_fractionfloat

Fraction of events to be lost.

Returns:

astropy.units.Quantity

Viewcone radius in degrees.

property core_distance_bins

Return bins for the core distance histogram.

property energy_bins

Return bins for the energy histogram.

plot_data(output_path=None)

Histogram plotting.

Parameters:

output_path: Path or str, optional

Directory to save plots. If None, plots will be displayed.

property view_cone_bins

Return bins for the viewcone histogram.

derive_corsika_limits_grid

Derive CORSIKA limits for a grid of parameters.

production_configuration.derive_corsika_limits_grid.generate_corsika_limits_grid(args_dict)

Generate CORSIKA limits for a grid of parameters.

Requires at least one event data file per parameter set.

Parameters:

args_dictdict

Dictionary containing command line arguments.

production_configuration.derive_corsika_limits_grid.write_results(results, args_dict)

Write the computed limits as astropy table to file.

Parameters:

resultslist[dict]

List of computed limits.

args_dictdict

Dictionary containing command line arguments.

derive_production_statistics

Calculate the event production statistics based on metrics.

Module for calculating the production event statistics based on statistical error metrics. Contains the ProductionStatisticsDerivator class, which derives the number of events for both the entire dataset and specific grid points. Event statistic is calculated using error metrics and the evaluator’s results.

class production_configuration.derive_production_statistics.ProductionStatisticsDerivator(evaluator, metrics: dict)

Derives the production statistics based on statistical error metrics.

Supports deriving statistics for both the entire dataset and specific grid points like energy values.

calculate_production_statistics_at_grid_point(grid_point: tuple) → Quantity

Derive the production statistics for a specific energy grid point.

Parameters:

grid_pointtuple

The grid point specifying energy, azimuth, zenith, NSB, and offset.

Returns:

float

The derived production statistics at the specified grid point (energy).

derive_statistics(return_sum: bool = True) → Quantity

Derive the production statistics based on statistical error metrics.

Parameters:

return_sumbool, optional

If True, returns the sum of production statistics for the entire set of MC events. If False, returns the production statistics for each grid point along the energy axis. Default is True.

Returns:

u.Quantity

If ‘return_sum’ is True, returns the total derived production statistics as a u.Quantity. If ‘return_sum’ is False, returns an array of production statistics along the energy axis as a u.Quantity.

derive_production_statistics_handler

Derives the required statistics for a requested set of production parameters through interpolation.

This module provides the ProductionStatisticsHandler class, which manages the workflow for derivation of required number of events for a simulation production using pre-defined metrics.

The module includes functionality to: - Initialize evaluators for statistical uncertainty calculations based on input parameters. - Perform interpolation using the initialized evaluators to estimate production statistics at a query point. - Write the results of the interpolation to an output file.

class production_configuration.derive_production_statistics_handler.ProductionStatisticsHandler(args_dict, output_path)

Handles the workflow for deriving production statistics.

This class manages the evaluation of statistical uncertainties from DL2 MC event files and performs interpolation to estimate the required number of events for a simulation production at a specified query point.

initialize_evaluators()

Initialize StatisticalUncertaintyEvaluator instances for the given grid point.

perform_interpolation()

Perform interpolation for the query point.

plot_production_statistics_comparison()

Plot the derived event statistics.

run()

Run the scaling and interpolation workflow.

write_output(production_statistics)

Write the derived event statistics to a file.

generate_production_grid

Module defines the GridGeneration class.

Used to generate a grid of simulation points based on flexible axes definitions such azimuth, zenith angle, night-sky background, and camera offset. The module handles axis binning, scaling and interpolation of energy thresholds, viewcone, and radius limits from a lookup table. Additionally, it allows for converting between Altitude/Azimuth and Right Ascension Declination coordinates. The resulting grid points are saved to a file.

class production_configuration.generate_production_grid.GridGeneration(axes: dict, coordinate_system: str = 'zenith_azimuth', observing_location=None, observing_time=None, lookup_table: str | None = None, telescope_ids: list | None = None)

Defines and generates a grid of simulation points based on flexible axes definitions.

This class generates a grid of points for a simulation based on parameters such as azimuth, zenith angle, night-sky background, and camera offset, taking into account axis definitions, scaling, and units and interpolating values for simulations from a lookup table.

convert_altaz_to_radec(alt, az)

Convert Altitude/Azimuth (AltAz) coordinates to Right Ascension/Declination (RA/Dec).

Parameters:

altfloat

Altitude angle in degrees.

azfloat

Azimuth angle in degrees.

Returns:

SkyCoord

SkyCoord object containing the RA/Dec coordinates.

Raises:

ValueError

If observing_time is not set.

convert_coordinates(grid_points: list[dict]) → list[dict]

Convert the grid points to RA/Dec coordinates if necessary.

Parameters:

grid_pointslist of dict

List of grid points, each represented as a dictionary with axis

names as keys and values.

Returns:

list of dict

The grid points with converted RA/Dec coordinates.

create_circular_binning(azimuth_range, num_bins)

Create bin centers for azimuth angles, handling circular wraparound (0 deg to 360 deg).

Parameters:

azimuth_rangetuple

(min_azimuth, max_azimuth), can wrap around 0 deg.

num_binsint

Number of bins.

Returns:

np.ndarray

Array of bin centers.

generate_grid() → list[dict]

Generate the grid based on the required axes and include interpolated limits.

Takes energy threshold, viewcone, and radius from the interpolated lookup table.

Returns:

list of dict

A list of grid points, each represented as a dictionary with axis names as keys and axis values as values. Axis values may include units where defined.

serialize_grid_points(grid_points, output_file=None)

Serialize the grid output and save to a file or print to the console.

serialize_quantity(value)

Serialize Quantity.

interpolation_handler

Handle interpolation between multiple StatisticalUncertaintyEvaluator instances.

class production_configuration.interpolation_handler.InterpolationHandler(evaluators, metrics: dict, grid_points_production: list)

Calculate the required events for production via interpolation from a grid.

This class provides methods to interpolate production statistics across a grid of parameter values (azimuth, zenith, NSB, offset) and energy.

build_grid_points_no_energy()

Build grid points without energy dimension.

Returns:

tuple

(production_statistics, grid_points_no_energy)

interpolate() → ndarray

Interpolate production statistics at the grid points specified in grid_points_production.

This method performs two types of interpolation: 1. Energy-independent interpolation using the sum of production statistics 2. Energy-dependent interpolation for each energy bin

Returns:

np.ndarray

Interpolated values at the query points.

plot_comparison(grid_point_index=0)

Plot a comparison between interpolated production statistics and reconstructed events.

Parameters:

grid_point_indexint, optional

Index of the grid point to plot, by default 0

Returns:

matplotlib.axes.Axes

The Axes object containing the plot.