simtools-production-derive-monte-carlo-statistics

Estimate required Monte Carlo statistics from trigger histograms.

Overview

This application estimates the total number of thrown Monte Carlo events required for a production simulation to achieve one of the following targets:

• target_relative_uncertainty requires every relevant energy bin to meet the requested relative statistical uncertainty.

• target_triggered_events requires the selected energy range to contain the requested number of triggered events.

Use optimization_energy_min and optimization_energy_max to limit the optimization range. The optional reduced core and view-cone radii report statistics for a smaller analysis region. Events can be re-weighted to a different power-law spectrum using the spectral_index argument.

Input and output

Role	Argument or file	Format	Description
Input	trigger_histogram_file	HDF5	Product from simtools-write-trigger-histograms.
Output	output_file	ECSV	Estimated Monte Carlo statistics.
Output	output_path	Directory	Result and optional diagnostic plots.

Set plot_diagnostics to generate plots of expected events and relative uncertainty.

Command line arguments

options

–help

show this help message and exit

–trigger_histogram_file

Path to the trigger-histogram file.

Required.

–array_layout_name

Optional array layout name(s) to select from a precomputed trigger-histogram file. If omitted, estimate statistics for all layouts available in the file.

–spectral_index

Target power-law spectral index. Reweight the simulated energy distribution from the source spectrum to this target spectrum.

–target_relative_uncertainty

Target relative statistical uncertainty for each relevant bin individually.

–target_triggered_events

Target total number of triggered events across the selected optimization range.

–optimization_energy_min

Optional lower bound of the optimization range.

–optimization_energy_max

Optional upper bound of the optimization range.

–reduced_core_radius

Optional reduced core scatter radius used for effective-area reporting (e.g., as derived from simtools-production-derive-corsika-limits).

–reduced_view_cone_radius

Optional reduced view-cone radius used for reporting required Monte Carlo statistics within a smaller angular cone.

–plot_diagnostics

Write diagnostic plots for expected events and relative uncertainty.

output

–output_file

Output data file.

–output_file_format

file format of output data

Default: ecsv.

–skip_output_validation

skip output data validation against schema

application

–show_options

Print available values for a supported option and exit.

Examples

Estimate Monte Carlo statistics from trigger counts

Determine event statistics for a target triggered-event count.

Application: simtools-production-derive-monte-carlo-statistics

Integration test: production_derive_monte_carlo_statistics_target_triggered_events.yml

Command

simtools-production-derive-monte-carlo-statistics --config tests/integration_tests/config/production_derive_monte_carlo_statistics_target_triggered_events.yml

Configuration

trigger_histogram_file: ${generated:gamma_diffuse_run000010_za20deg_azm000deg_North_CTAO-North-Alpha_7.0.0_test.trigger_histograms.hdf5}
optimization_energy_max: 300 TeV
optimization_energy_min: 0.3 TeV
reduced_core_radius: 200 m
spectral_index: -2.0
output_file: mc_statistics_events.ecsv
output_path: simtools-output
target_triggered_events: 100
plot_diagnostics: true

Estimate Monte Carlo statistics from uncertainty

Determine event statistics for a target relative uncertainty over an energy range.

Application: simtools-production-derive-monte-carlo-statistics

Integration test: production_derive_monte_carlo_statistics_target_uncertainty.yml

Command

simtools-production-derive-monte-carlo-statistics --config tests/integration_tests/config/production_derive_monte_carlo_statistics_target_uncertainty.yml

Configuration

trigger_histogram_file: ${generated:gamma_diffuse_run000010_za20deg_azm000deg_North_CTAO-North-Alpha_7.0.0_test.trigger_histograms.hdf5}
optimization_energy_max: 100 TeV
optimization_energy_min: 0.1 TeV
reduced_core_radius: 200 m
reduced_view_cone_radius: 7.5 deg
spectral_index: -1.5
output_file: mc_statistics_uncertainty.ecsv
output_path: simtools-output
target_relative_uncertainty: 0.1
plot_diagnostics: true