Improve determination of energy limits / plotting

src/simtools/applications/production_derive_corsika_limits.py

@@ -12,33 +12,43 @@
 
 Broad-range simulations in this context are simulation sets generated with wide-ranging
 definitions for above parameters.
-Limits are computed based on a configurable maximum event loss fraction
-and a minimum number of events lost after cuts.
+Limits are computed from configurable per-axis allowed-loss settings.
 Results are provided as a table with the following columns:
 
-+---------------------+-----------+--------+-----------------------------------------------+
-| Field               | Data Type | Units  | Description                                   |
-+=====================+===========+========+===============================================+
-| primary_particle    | string    |        | Particle type (e.g., gamma, proton).          |
-+---------------------+-----------+--------+-----------------------------------------------+
-| array_name          | string    |        | Array name (custom or as defined in           |
-|                     |           |        | 'array_layouts').                             |
-+---------------------+-----------+--------+-----------------------------------------------+
-| telescope_ids       | string    |        | Comma-separated list of telescope IDs         |
-|                     |           |        | of this array.                                |
-+---------------------+-----------+--------+-----------------------------------------------+
-| zenith              | float64   | deg    | Direction of array pointing zenith.           |
-+---------------------+-----------+--------+-----------------------------------------------+
-| azimuth             | float64   | deg    | Direction of array pointing azimuth.          |
-+---------------------+-----------+--------+-----------------------------------------------+
-| nsb_level           | float64   |        | Night sky background level.                   |
-+---------------------+-----------+--------+-----------------------------------------------+
-| lower_energy_limit  | float64   | TeV    | Derived lower energy limit (**ERANGE**)       |
-+---------------------+-----------+--------+-----------------------------------------------+
-| upper_radius_limit  | float64   | m      | Derived upper core distance limit (**CSCAT**) |
-+---------------------+-----------+--------+-----------------------------------------------+
-| viewcone_radius     | float64   | deg    | Derived viewcone radius limit (**VIEWCONE**)  |
-+---------------------+-----------+--------+-----------------------------------------------+
++---------------------------+-----------+--------+----------------------------------------------+
+| Field                     | Data Type | Units  | Description                                  |
++===========================+===========+========+==============================================+
+| production_index          | int64     |        | Production index for multi-production runs.  |
++---------------------------+-----------+--------+----------------------------------------------+
+| event_data_file           | string    |        | Input event-data pattern for this row.       |
++---------------------------+-----------+--------+----------------------------------------------+
+| primary_particle          | string    |        | Particle type (e.g., gamma, proton).         |
++---------------------------+-----------+--------+----------------------------------------------+
+| array_name                | string    |        | Array name (custom or as defined in          |
+|                           |           |        | array_layouts).                              |
++---------------------------+-----------+--------+----------------------------------------------+
+| zenith                    | float64   | deg    | Direction of array pointing zenith.          |
++---------------------------+-----------+--------+----------------------------------------------+
+| azimuth                   | float64   | deg    | Direction of array pointing azimuth.         |
++---------------------------+-----------+--------+----------------------------------------------+
+| nsb_level                 | float64   |        | Night sky background level.                  |
++---------------------------+-----------+--------+----------------------------------------------+
+| lower_energy_limit        | float64   | TeV    | Derived lower energy limit (**ERANGE**).     |
++---------------------------+-----------+--------+----------------------------------------------+
+| upper_radius_limit        | float64   | m      | Derived upper core distance                  |
+|                           |           |        | (**CSCAT**).                                 |
++---------------------------+-----------+--------+----------------------------------------------+
+| viewcone_radius           | float64   | deg    | Derived viewcone radius (**VIEWCONE**).      |
++---------------------------+-----------+--------+----------------------------------------------+
+| br_energy_min             | float64   | TeV    | Energy min from broad-range simulations.     |
++---------------------------+-----------+--------+----------------------------------------------+
+| br_energy_max             | float64   | TeV    | Energy max from broad-range simulations.     |
++---------------------------+-----------+--------+----------------------------------------------+
+| br_core_scatter_max       | float64   | m      | Core scatter max from broad-range            |
+|                           |           |        | simulations.                                 |
++---------------------------+-----------+--------+----------------------------------------------+
+| br_viewcone_max           | float64   | deg    | Viewcone max from broad-range simulations.   |
++---------------------------+-----------+--------+----------------------------------------------+
 
 The input event data files are generated using the application simtools-generate-simtel-event-data
 and are required for each point in the observational parameter space (e.g., array pointing
@@ -58,11 +68,11 @@
     multi-production processing.
 telescope_ids (str, optional)
     Custom array layout file containing telescope IDs.
-loss_fraction (float, required)
-    Maximum event-loss fraction for limit computation.
-loss_min_events (int, optional)
-    Minimum number of events that must be lost after applying a limit.
-    Default: 10.
+allowed_losses (str, required, repeatable)
+    Per-axis allowed-loss tuple in the form
+    ``axis,fraction,min_events``.
+    Use once per axis (energy, core_distance, angular_distance), or use ``all``
+    to set all axes and optionally override selected axes with additional entries.
 plot_histograms (bool, optional)
     Plot histograms of the event data.
 output_file (str, optional)
@@ -83,8 +93,9 @@
     simtools-production-derive-corsika-limits \\
         --event_data_file event_dat_file.hdf5 \\
         --array_layout_name alpha,beta \\
-        --loss_fraction 1e-6 \\
-        --loss_min_events 10 \\
+        --allowed_losses energy,1e-6,10 \
+        --allowed_losses core_distance,1e-6,10 \
+        --allowed_losses angular_distance,1e-6,10 \
         --plot_histograms \\
         --output_file corsika_simulation_limits.ecsv
 
@@ -95,8 +106,7 @@
     simtools-production-derive-corsika-limits \\
         --event_data_file event_dat_file.hdf5 \\
         --telescope_ids path/to/telescope_configs.yaml \\
-        --loss_fraction 1e-6 \\
-        --loss_min_events 10 \\
+        --allowed_losses all,1e-6,10 \
         --plot_histograms \\
         --output_file corsika_simulation_limits.ecsv
 
@@ -108,8 +118,7 @@
         --event_data_file pattern_1_*.hdf5 \\
         --event_data_file pattern_2_*.hdf5 \\
         --array_layout_name alpha \\
-        --loss_fraction 1e-6 \\
-        --loss_min_events 10 \\
+        --allowed_losses all,1e-6,10 \
         --plot_histograms \\
         --n_workers 4 \\
         --output_file corsika_simulation_limits.ecsv
@@ -140,17 +149,18 @@ def _add_arguments(parser):
         required=True,
     )
     parser.add_argument(
-        "--loss_fraction",
-        type=float,
+        "--allowed_losses",
+        type=str,
         required=True,
-        help="Maximum event-loss fraction for limit computation.",
-    )
-    parser.add_argument(
-        "--loss_min_events",
-        type=int,
-        required=False,
-        default=10,
-        help="Minimum number of events that must be lost after applying a limit.",
+        nargs="+",
+        action="extend",
+        metavar="AXIS,FRACTION,MIN_EVENTS",
+        help=(
+            "Per-axis allowed losses as axis,fraction,min_events. Repeat this argument "
+            "for each axis using canonical names energy, core_distance, angular_distance, "
+            "or use all. "
+            "Example: --allowed_losses energy,1e-6,10"
+        ),
     )
     parser.add_argument(
         "--plot_histograms",