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_errors_grid_point

Evaluate statistical uncertainties from DL2 MC event files.

class production_configuration.calculate_statistical_errors_grid_point.StatisticalErrorEvaluator(file_path: str, file_type: str, metrics: dict[str, float], grid_point: tuple[float, float, float, float, float] | None = None)

Evaluates statistical uncertainties from a DL2 MC event file.

Parameters:

file_pathstr

Path to the DL2 MC event file.

file_typestr

Type of the file, either ‘point-like’ or ‘cone’.

metricsdict, optional

Dictionary of metrics to evaluate. Default is None.

grid_pointtuple, optional

Tuple specifying the 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 error for effective area.

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:

dict

Dictionary with overall maximum errors for each metric.

calculate_uncertainty_effective_area()

Calculate the uncertainties on the effective collection area.

Returns:

errorsdict

Dictionary with uncertainties for the file.

compute_efficiency_and_errors(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_errorsarray

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_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.

event_scaler

Calculate the scaled number of events based on metrics.

Module for scaling events based on statistical error metrics. Contains the EventScaler class, which scales the number of events for both the entire dataset and specific grid points. Scaling factors are calculated using error metrics and the evaluator’s results.

class production_configuration.event_scaler.EventScaler(evaluator, metrics: dict)

Scales the number of events based on statistical error metrics.

Supports scaling both the entire dataset and specific grid points like energy values.

calculate_scaled_events_at_grid_point(grid_point: tuple) → Quantity

Calculate the scaled number of events for a specific energy grid point.

Parameters:

grid_pointtuple

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

Returns:

float

The scaled number of events at the specified grid point (energy).

scale_events(return_sum: bool = True) → Quantity

Calculate the scaled number of events based on statistical error metrics.

Parameters:

return_sumbool, optional

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

Returns:

u.Quantity

If ‘return_sum’ is True, returns the total scaled number of events as a u.Quantity. If ‘return_sum’ is False, returns an array of scaled events along the energy axis as a u.Quantity.

generate_simulation_config

Derives simulation configuration parameters for a grid point based on several metrics.

class production_configuration.generate_simulation_config.SimulationConfig(grid_point: dict[str, float], file_path: str, file_type: str, metrics: dict[str, float] | None = None)

Configures simulation parameters for a specific grid point.

Parameters:

grid_pointdict

Dictionary representing a grid point with azimuth, elevation, and night sky background.

file_pathstr

Path to the DL2 MC event file for statistical uncertainty evaluation.

file_typestr

Type of the DL2 MC event file (‘point-like’ or ‘cone’).

metricsdict, optional

Dictionary of metrics to evaluate.

calculate_required_events() → int

Calculate the required number of simulated events based on statistical error metrics.

Uses the EventScaler to scale the events.

Returns:

int

The number of simulated events required.

configure_simulation() → dict[str, float]

Configure the simulation parameters for the grid point.

Returns:

dict

A dictionary with simulation parameters such as core scatter area,

viewcone, and number of simulated events.

interpolation_handler

Interpolates between instances of StatisticalErrorEvaluator using EventScaler.

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

Handle interpolation between multiple StatisticalErrorEvaluator instances.

interpolate(query_points: ndarray) → ndarray

Interpolate the number of simulated events given query points.

Parameters:

query_pointsnp.ndarray

Array of query points with shape (n, 5), where n is the number of points, and 5 represents (energy, azimuth, zenith, nsb, offset).

Returns:

np.ndarray

Interpolated values at the query points.

interpolate_energy_threshold(query_point: ndarray) → float

Interpolate the energy threshold for a given grid point.

Parameters:

query_pointnp.ndarray

Array specifying the grid point (energy, azimuth, zenith, NSB, offset).

Returns:

float

Interpolated energy threshold.

plot_comparison(evaluator)

Plot a comparison between the simulated, scaled, and reconstructed events.

Parameters:

evaluatorStatisticalErrorEvaluator

The evaluator for which to plot the comparison.

limits_calculation

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

class production_configuration.limits_calculation.LimitCalculator(event_data_file_tables)

Compute thresholds/limits for energy, radial distance, and viewcone.

Histograms are generated with simtools-generate-simtel-array-histograms with –hdf5 flag.

Event data is read from the generated HDF5 file from the following tables: - angle_to_observing_position__triggered_showers_ for the viewcone limit. - event_weight__ra3d__log10_e__ for the energy and radial distance limit.

Parameters:

event_data_filelist of astropy.table.Table

The list of tables containing the event data.

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_radial_distance(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.

Parameters:

loss_fractionfloat

Fraction of events to be lost.

Returns:

astropy.units.Quantity

Viewcone radius in degrees.

get_bin_edges_and_units(table, axis='x')

Extract bin edges and units from the table metadata.

Parameters:

tableastropy.table.Table

Table containing the event data.

Returns:

tuple

Tuple containing the bin edges and their units.