gammasimtools 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

simtools/applications/derive_mirror_rnda.py

@@ -1,227 +1,161 @@
 #!/usr/bin/python3
 
-r"""
-    Derive mirror random reflection angle (mirror roughness) of a single mirror panel.
-
-    Description
-    -----------
-
-    This application derives the value of the simulation model parameter
-    *mirror_reflection_random_angle* using measurements of the focal length
-    and point-spread function (PSF) of individual mirror panels.
-    This parameter is sometimes referred to as the "mirror roughness".
-
-    PSF measurements are provided by one of the following options:
-
-        * mean and sigma value obtained from the measurement of containment diameters of a number of
-          mirror panels in cm (``--psf_measurement_containment_mean`` and
-          ``--psf_measurement_containment_sigma``)
-        * file (table) with measured PSF for each mirror panel spot size (``--psf_measurement``)
-
-    The containment fraction used for the PSF diameter calculation is set through
-    the argument ``--containment_fraction`` (typically 0.8 = 80%; called below D80).
-
-    Mirror panels are simulated individually, using one of the following options to set the
-    mirror panel focal length:
-
-        * file (table) with measured focal lengths per mirror panel
-          (provided through ``--mirror_list``)
-        * randomly generated focal lengths using an expected spread (value given through
-          ``--random_focal_length``) around the mean focal length (provided through the
-          Model Parameters DB). This option is switched with ``--use_random_focal_length``.
-
-    The tuning algorithm requires a starting value for the random reflection angle. This is either
-    taken from the Model Parameters DB (default) or can be set using the argument ``--rnda``.
-
-    Ray-tracing simulations are performed for single mirror configurations for each
-    mirror given in the mirror list. The mean simulated containment diameter for all the mirrors
-    is compared with the mean measured containment diameter. The algorithm defines a new value for
-    the random reflection angle based on the sign of the difference between measured and simulated
-    containment diameters and a new set of simulations is performed. This process is repeated
-    until the sign of the difference changes, meaning that the two final values of the random
-    reflection angle brackets the optimal. These two values are used to find the optimal one by
-    a linear interpolation. Finally, simulations are performed by using the interpolated value,
-    which is defined as the desired optimal.
-
-    The option ``--no_tuning`` can be used if one only wants to simulate one value for the random
-    reflection angle and compare the results with the measured ones.
-
-    Results of the tuning are plotted. See examples of the PSF containment diameter
-    D80 vs random reflection angle plot, on the left, and the D80 distributions
-    (per mirror panel), on the right.
-
-    .. _derive_rnda_plot:
-    .. image:: images/derive_mirror_rnda_North-MST-FlashCam-D.png
-      :width: 49 %
-    .. image:: images/derive_mirror_rnda_North-MST-FlashCam-D_D80-distributions.png
-      :width: 49 %
-
-    This application uses the following software tools:
-
-        - sim_telarray/bin/sim_telarray
-        - sim_telarray/bin/rx (optional)
-
-    Command line arguments
-    ----------------------
-    telescope (str, required)
-        Telescope name (e.g. LSTN-01, SSTS-25)
-    model_version (str, optional)
-        Model version
-    psf_measurement (str, optional)
-        Table with results from PSF measurements for each mirror panel spot size
-    psf_measurement_containment_mean (float, required)
-        Mean of measured containment diameter [cm]
-    psf_measurement_containment_sigma (float, optional)
-        Std dev of measured containment diameter [cm]
-    containment_fraction (float, required)
-        Containment fraction for diameter calculation
-    rnda (float, optional)
-        Starting value of mirror_reflection_random_angle [deg]. If not given, the value from the
-        default model is read from the simulation model database.
-    mirror_list (file, optional)
-        Table with mirror ID and panel radius.
-    use_random_focal_length (activation mode, optional)
-        Use random focal lengths, instead of the measured ones. The argument random_focal_length
-        can be used to replace the default random_focal_length from the model.
-    random_focal_length (float, optional)
-        Value of the random focal lengths to replace the default random_focal_length. Only used if
-        'use_random_focal_length' is activated.
-    random_focal_length_seed (int, optional)
-        Seed for the random number generator used for focal length variation.
-    no_tuning (activation mode, optional)
-        Turn off the tuning - A single case will be simulated and plotted.
-    test (activation mode, optional)
-        If activated, application will be faster by simulating only few mirrors.
-
-    Example
-    -------
-    Derive mirror random reflection angle for a large-sized telescope (LSTS),
-    simulation production 6.0.0
-
-    .. code-block:: console
-
-        simtools-derive-mirror-rnda \\
-            --site South \\
-            --telescope LSTS-design \\
-            --model_version 6.0.0 \\
-            --containment_fraction 0.8 \\
-            --mirror_list ./tests/resources/mirror_list_CTA-N-LST1_v2019-03-31_rotated.ecsv
-            --rnda 0.003 \\
-            --psf_measurement_containment_mean 1.4 \\
-
-    Expected final print-out message:
-
-    .. code-block:: console
-
-        Measured D80:
-        Mean = 1.400 cm
-
-        Simulated D80:
-        Mean = 1.406 cm, StdDev = 0.005 cm
-
-        mirror_random_reflection_angle
-        Previous value = 0.003000
-        New value = 0.003824
+r"""Derive mirror random reflection angle based on per-mirror PSF diameter optimization.
+
+Description
+-----------
+
+This application derives the value of the simulation model parameter
+*mirror_reflection_random_angle* using measurements of a PSF containment diameter
+and focal length of individual mirror panels.
+
+The optimization uses percentage difference as the metric::
+
+    pct_diff = 100 * (simulated_psf - measured_psf) / measured_psf
+
+Each mirror is optimized individually, and the final RNDA is the average of all
+per-mirror optimized values.
+
+Command line arguments
+----------------------
+
+site (str, required)
+    North or South.
+telescope (str, required)
+    Telescope name (e.g. LSTN-01, SSTS-25).
+model_version (str, optional)
+    Model version.
+data (str, required)
+    ECSV file with PSF diameter (mm) per mirror.
+    Accepted column names: psf_opt, psf, or d80.
+fraction (float, optional)
+    PSF containment fraction for diameter calculation (e.g. 0.8 for D80, 0.95 for D95).
+    Default: 0.8.
+threshold (float, optional)
+    Convergence threshold for percentage difference (e.g. 0.05 for 5%).
+    Default: 0.05.
+learning_rate (float, optional)
+    Learning rate for gradient descent. Default: 0.001.
+test (optional)
+    Only optimize a small number of mirrors.
+n_workers (int, optional)
+    Number of parallel worker processes to use. Default: 0 (auto chooses maximum).
+number_of_mirrors_to_test (int, optional)
+    Number of mirrors to optimize when --test is used. Default: 10.
+psf_hist (str, optional)
+    If activated, write a histogram comparing measured vs simulated PSF diameter distributions.
+cleanup (optional)
+    Remove intermediate files (patterns: ``*.log``, ``*.lis*``, ``*.dat``)
+    from output.
+
+Example
+-------
+
+.. code-block:: console
+
+    simtools-derive-mirror-rnda \
+        --site North \
+        --telescope LSTN-01 \
+        --model_version 7.0.0 \
+        --data tests/resources/MLTdata-preproduction.ecsv \
+        --parameter_version 1.0.0 \
+        --test --psf_hist --cleanup
 
 """
 
+from pathlib import Path
+
 from simtools.application_control import get_application_label, startup_application
 from simtools.configuration import configurator
 from simtools.ray_tracing.mirror_panel_psf import MirrorPanelPSF
+from simtools.ray_tracing.psf_parameter_optimisation import cleanup_intermediate_files
 
 
 def _parse():
     """Parse command line configuration."""
     config = configurator.Configurator(
-        description="Derive mirror random reflection angle.", label=get_application_label(__file__)
+        description="Derive mirror RNDA using per-mirror PSF diameter optimization.",
+        label=get_application_label(__file__),
     )
-    psf_group = config.parser.add_mutually_exclusive_group()
-    psf_group.add_argument(
-        "--psf_measurement_containment_mean",
-        help="Mean of measured PSF containment diameter [cm]",
-        type=float,
-        required=False,
-    )
-    psf_group.add_argument(
-        "--psf_measurement",
-        help="Results from PSF measurements for each mirror panel spot size",
+    config.parser.add_argument(
+        "--data",
+        help="ECSV file with a PSF diameter column (mm) per mirror",
         type=str,
-        required=False,
+        required=True,
     )
     config.parser.add_argument(
-        "--psf_measurement_containment_sigma",
-        help="Std dev of measured PSF containment diameter [cm]",
+        "--threshold",
+        help="Convergence threshold for percentage difference.",
         type=float,
         required=False,
+        default=0.05,
     )
     config.parser.add_argument(
-        "--containment_fraction",
-        help="Containment fraction for diameter calculation (in interval 0,1)",
-        type=config.parser.efficiency_interval,
-        required=False,
-        default=0.8,
-    )
-    config.parser.add_argument(
-        "--rnda",
-        help="Starting value of mirror_reflection_random_angle",
+        "--learning_rate",
+        help="Learning rate for gradient descent.",
         type=float,
         required=False,
-        default=0.0,
-    )
-    config.parser.add_argument(
-        "--mirror_list",
-        help=("Mirror list file to replace the default one."),
-        type=str,
-        required=False,
+        default=0.001,
     )
     config.parser.add_argument(
-        "--rtol_psf_containment",
-        help="Relative tolerance for the containment diameter (default is 0.1).",
+        "--fraction",
+        help=(
+            "PSF containment fraction for diameter calculation (e.g., 0.8 for D80, 0.95 for D95)."
+        ),
         type=float,
-        required=False,
-        default=0.1,
+        default=0.8,
     )
     config.parser.add_argument(
-        "--use_random_focal_length",
-        help=("Use random focal lengths."),
-        action="store_true",
+        "--n_workers",
+        help="Number of parallel worker processes to use.",
+        type=int,
         required=False,
+        default=0,
     )
     config.parser.add_argument(
-        "--random_focal_length",
-        help=(
-            "Value of the random focal length. Only used if 'use_random_focal_length' is activated."
-        ),
-        default=None,
-        type=float,
+        "--number_of_mirrors_to_test",
+        help="Number of mirrors to optimize when --test is used.",
+        type=int,
         required=False,
+        default=10,
     )
     config.parser.add_argument(
-        "--random_focal_length_seed",
-        help="Seed for the random number generator used for focal length variation.",
-        type=int,
-        required=False,
+        "--psf_hist",
+        nargs="?",
+        const="psf_distributions.png",
         default=None,
+        help=(
+            "Write a histogram comparing measured vs simulated PSF diameter distributions. "
+            "Optionally provide a filename (relative to output dir unless absolute)."
+        ),
     )
     config.parser.add_argument(
-        "--no_tuning",
-        help="no tuning of random_reflection_angle (a single case will be simulated).",
+        "--cleanup",
         action="store_true",
-        required=False,
+        default=False,
+        help=(
+            "Remove intermediate files from the output directory (patterns: *.log, *.lis*, *.dat)."
+        ),
     )
     return config.initialize(
-        db_config=True, output=True, simulation_model=["telescope", "model_version"]
+        db_config=True,
+        output=True,
+        simulation_model=["telescope", "model_version", "site", "parameter_version"],
     )
 
 
 def main():
-    """Derive mirror random reflection angle of a single mirror panel."""
+    """Derive mirror random reflection angle using per-mirror PSF diameter optimization."""
     app_context = startup_application(_parse)
-
     panel_psf = MirrorPanelPSF(app_context.args.get("label"), app_context.args)
-    panel_psf.derive_random_reflection_angle(save_figures=True)
-    panel_psf.print_results()
+    panel_psf.optimize_with_gradient_descent()
     panel_psf.write_optimization_data()
+    if app_context.args.get("psf_hist"):
+        panel_psf.write_psf_histogram()
+
+    if app_context.args.get("cleanup"):
+        output_dir = Path(app_context.args.get("output_path", "."))
+        cleanup_intermediate_files(output_dir)
 
 
 if __name__ == "__main__":

simtools/applications/generate_corsika_histograms.py

@@ -50,8 +50,25 @@ r"""
             --file_lablels label1 label2 \\
             --pdf_file_name test.pdf
 
+    Notes
+    -----
+    The typical use case of this application is to generate lateral photon density distribution
+    to compare different CORSIKA simulation settings or different CORSIKA versions. The following
+    steps are recommended:
+
+        - generate a 'star'-like array of telescopes with the 'simtools-generate-regular-arrays'
+          application. There should be a sufficient number of telescopes (e.g. 50 or more) in the
+          layout with non-overlapping telescope definitions
+
+        - run CORSIKA simulations with the desired settings using this telescope layout (use the
+          'overwrite_model_parameters' option to point to the generated layout simulation model
+          change file (in the format given by 'simulation_models_info.schema.yml').
+
+        - run this application to generate the histograms for the produced CORSIKA IACT output
 """
 
+from astropy import units as u
+
 from simtools.application_control import get_application_label, startup_application
 from simtools.configuration import configurator
 from simtools.corsika.corsika_histograms import CorsikaHistograms
@@ -78,6 +95,22 @@ def _parse():
         nargs="+",
         required=None,
     )
+    config.parser.add_argument(
+        "--normalization",
+        help="Normalization method for histograms. Options: 'per-telescope', 'per-bin'",
+        type=str,
+        choices=["per-telescope", "per-bin"],
+        default="per-telescope",
+    )
+    config.parser.add_argument(
+        "--axis_distance",
+        help=(
+            "Distance from x/y axes to consider when calculating "
+            "the lateral density profiles (in meters)."
+        ),
+        type=float,
+        default=1000.0,
+    )
     config.parser.add_argument(
         "--pdf_file_name",
         help="Save histograms into a pdf file.",
@@ -93,7 +126,11 @@ def main():
 
     all_histograms = []
     for input_file in app_context.args["input_files"]:
-        corsika_histograms = CorsikaHistograms(input_file)
+        corsika_histograms = CorsikaHistograms(
+            input_file,
+            normalization_method=app_context.args["normalization"],
+            axis_distance=app_context.args["axis_distance"] * u.m,
+        )
         corsika_histograms.fill()
         all_histograms.append(corsika_histograms)
 

simtools/applications/generate_regular_arrays.py

@@ -1,15 +1,25 @@
 #!/usr/bin/python3
 
 """
-Make a regular array of telescopes and save it as astropy table.
+Make a regular array of telescopes and save it to file.
 
-The arrays consist of one telescope at the center of the array and or of 4 telescopes
-in a square grid. These arrays are used for trigger rate simulations.
+Arrays can consist of single (central) telescopes, square grids or star-like (with
+telescopes arranged on main axes) patterns.  All telescopes in the array are of
+the same type and are placed at regular distances.
 
-The array layout files created will be available at the data/layout directory.
+Output files are saved as astropy tables in ASCII ECSV format and in the simtools format
+required to be used for the overwrite model parameter configuration.
 
 Command line arguments
 ----------------------
+telescope_type (str)
+    Type of telescope (e.g., LST, MST, SST).
+n_telescopes (int)
+    Number of telescopes in the array.
+telescope_distance (float)
+    Distance between telescopes in the array (in meters).
+array_shape (str)
+    Shape of the array ('square', 'star').
 site (str, required)
     observatory site (e.g., North or South).
 model_version (str, optional)
@@ -31,23 +41,38 @@ import astropy.units as u
 import simtools.data_model.model_data_writer as writer
 from simtools.application_control import get_application_label, startup_application
 from simtools.configuration import configurator
-from simtools.layout.array_layout_utils import create_regular_array
-
-# Telescope distances for 4 tel square arrays
-# !HARDCODED
-telescope_distance = {"LST": 57.5 * u.m, "MST": 70 * u.m, "SST": 80 * u.m}
+from simtools.layout.array_layout_utils import create_regular_array, write_array_elements_info_yaml
 
 
 def _parse():
     config = configurator.Configurator(
         label=get_application_label(__file__),
-        description=(
-            "Generate a regular array of telescope and save as astropy table.\n"
-            "Default telescope distances for 4 telescope square arrays are: \n"
-            f"  LST: {telescope_distance['LST']}\n"
-            f"  MST: {telescope_distance['MST']}\n"
-            f"  SST: {telescope_distance['SST']}\n"
-        ),
+        description=("Generate a regular array of telescope and save as astropy table."),
+    )
+    config.parser.add_argument(
+        "--telescope_type",
+        help="Type of telescope (e.g., LST, MST, SST).",
+        type=str,
+        default="LST",
+    )
+    config.parser.add_argument(
+        "--n_telescopes",
+        help="Number of telescopes in the array.",
+        type=int,
+        default=4,
+    )
+    config.parser.add_argument(
+        "--telescope_distance",
+        help="Distance between telescopes in the array (in meters).",
+        type=float,
+        default=50.0,
+    )
+    config.parser.add_argument(
+        "--array_shape",
+        help="Shape of the array (e.g., 'square', 'star').",
+        type=str,
+        default="square",
+        choices=["square", "star"],
     )
     return config.initialize(
         db_config=False, simulation_model=["site", "model_version"], output=True
@@ -55,32 +80,44 @@ def _parse():
 
 
 def main():
-    """Create layout array files (ecsv) of regular arrays."""
+    """Create layout array files of regular arrays."""
     app_context = startup_application(_parse)
 
-    if app_context.args["site"] == "South":
-        array_list = ["1SST", "4SST", "1MST", "4MST", "1LST", "4LST"]
-    else:
-        array_list = ["1MST", "4MST", "1LST", "4LST"]
-
-    for array_name in array_list:
-        app_context.logger.info(f"Processing array {array_name}")
+    n_tel = app_context.args["n_telescopes"]
+    tel_type = app_context.args["telescope_type"]
+    tel_dist = app_context.args["telescope_distance"] * u.m
+    shape = app_context.args["array_shape"]
+
+    array_name = f"{n_tel}{tel_type}-{shape}"
+    app_context.logger.info(f"Processing array {array_name}")
+
+    array_table = create_regular_array(
+        array_name,
+        app_context.args["site"],
+        n_telescopes=n_tel,
+        telescope_type=tel_type,
+        telescope_distance=tel_dist,
+        shape=shape,
+    )
 
-        array_table = create_regular_array(
-            array_name, app_context.args["site"], telescope_distance=telescope_distance
+    output_file = app_context.args.get("output_file")
+    if output_file:
+        output_path = Path(output_file)
+        output_file = output_path.with_name(
+            f"{output_path.stem}-{app_context.args['site']}-{array_name}{output_path.suffix}"
         )
 
-        output_file = app_context.args.get("output_file")
-        if output_file:
-            output_path = Path(output_file)
-            output_file = output_path.with_name(
-                f"{output_path.stem}-{app_context.args['site']}-{array_name}{output_path.suffix}"
-            )
-        writer.ModelDataWriter.dump(
-            args_dict=app_context.args,
+        data_writer = writer.ModelDataWriter(
             output_file=output_file,
-            metadata=None,
-            product_data=array_table,
+            output_file_format=app_context.args.get("output_file_format", "ascii.ecsv"),
+        )
+        data_writer.write(metadata=None, product_data=array_table)
+
+        write_array_elements_info_yaml(
+            array_table,
+            app_context.args["site"],
+            app_context.args["model_version"],
+            Path(data_writer.output_file).with_suffix(".info.yml"),
         )
 
 

simtools/applications/simulate_flasher.py

@@ -45,8 +45,6 @@ light_source (str, required)
     Calibration light source, e.g., MSFx-FlashCam
 number_of_events (int, optional):
     Number of events to simulate (default: 1).
-output_prefix (str, optional):
-    Prefix for output files (default: empty).
 model_version (str, optional)
     Version of the simulation model.
 array_layout_name (str, optional)
@@ -89,13 +87,6 @@ def _parse():
         default=1,
         required=False,
     )
-    config.parser.add_argument(
-        "--output_prefix",
-        help="Prefix for output files",
-        type=str,
-        default=None,
-        required=False,
-    )
     return config.initialize(
         db_config=True,
         simulation_model=["site", "layout", "telescope", "model_version"],
@@ -123,14 +114,13 @@ def main():
             label=app_context.args.get("label"),
         )
     elif app_context.args["run_mode"] == "direct_injection":
-        light_source = Simulator(
-            args_dict=app_context.args,
-            label=app_context.args.get("label"),
-        )
+        light_source = Simulator(label=app_context.args.get("label"))
     else:
         raise ValueError(f"Unsupported run_mode: {app_context.args['run_mode']}")
 
     light_source.simulate()
+    light_source.verify_simulations()
+
     app_context.logger.info("Flasher simulation completed.")
 
 

simtools/applications/simulate_illuminator.py

@@ -49,8 +49,6 @@ light_source_position (float, float, float, optional)
     m. If not set, the position from the simulation model is used.
 light_source_pointing (float, float, float, optional)
     Light source pointing direction. If not set, the pointing from the simulation model is used.
-output_prefix (str, optional)
-    Prefix for output files (default: empty).
 """
 
 from simtools.application_control import get_application_label, startup_application
@@ -100,13 +98,6 @@ def _parse():
         default=1,
         required=False,
     )
-    config.parser.add_argument(
-        "--output_prefix",
-        help="Prefix for output files (default: empty)",
-        type=str,
-        default=None,
-        required=False,
-    )
     return config.initialize(
         db_config=True,
         simulation_model=["telescope", "model_version"],
@@ -119,10 +110,11 @@ def main():
     app_context = startup_application(_parse)
 
     light_source = SimulatorLightEmission(
-        light_emission_config=app_context.args,
+        light_emission_config={**app_context.args, "run_mode": "illuminator"},
         label=app_context.args.get("label"),
     )
     light_source.simulate()
+    light_source.verify_simulations()
 
 
 if __name__ == "__main__":

simtools/applications/simulate_pedestals.py

@@ -108,7 +108,7 @@ def main():
     """Simulate pedestal events."""
     app_context = startup_application(_parse)
 
-    simulator = Simulator(label=app_context.args.get("label"), args_dict=app_context.args)
+    simulator = Simulator(label=app_context.args.get("label"))
     simulator.simulate()