gammasimtools 0.18.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

simtools/applications/derive_mirror_rnda.py

@@ -1,18 +1,15 @@
 #!/usr/bin/python3
 
 r"""
-    Derive the simulation model parameter mirror_reflection_random_angle.
-
-    This parameter, often referred to as "mirror roughness," is used to align the simulation
-    with the measured containment diameter of the optical point-spread function (PSF) for
-    individual mirror panels.
+    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 PSF of individual mirror panels.
+    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:
 
@@ -22,7 +19,7 @@ r"""
         * 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%).
+    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:
@@ -37,7 +34,7 @@ r"""
     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
+    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
@@ -67,7 +64,7 @@ r"""
     Command line arguments
     ----------------------
     telescope (str, required)
-        Telescope name (e.g. North-LST-1, South-SST-D, ...)
+        Telescope name (e.g. LSTN-01, SSTS-25)
     model_version (str, optional)
         Model version
     psf_measurement (str, optional)
@@ -89,6 +86,8 @@ r"""
     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)
@@ -96,8 +95,8 @@ r"""
 
     Example
     -------
-    Derive mirror random reflection angle for a mid-sized telescope (MST),
-    simulation production 5.0.0
+    Derive mirror random reflection angle for a large-sized telescope (LSTS),
+    simulation production 6.0.0
 
     .. code-block:: console
 
@@ -200,6 +199,13 @@ def _parse(label):
         type=float,
         required=False,
     )
+    config.parser.add_argument(
+        "--random_focal_length_seed",
+        help="Seed for the random number generator used for focal length variation.",
+        type=int,
+        required=False,
+        default=None,
+    )
     config.parser.add_argument(
         "--no_tuning",
         help="no tuning of random_reflection_angle (a single case will be simulated).",

simtools/applications/derive_psf_parameters.py

@@ -17,6 +17,16 @@ r"""
     the Root Mean Squared Deviation between data and simulations. The range in which the \
     parameter are drawn uniformly are defined based on the previous value on the telescope model.
 
+    The optimization workflow includes:
+
+    * Loading and preprocessing PSF data from measurement files
+    * Generating random parameter combinations for optimization
+    * Running ray-tracing simulations for each parameter set
+    * Calculating RMSD between measured and simulated PSF curves
+    * Identifying the best-fit parameters with minimum RMSD
+    * Creating comprehensive plots and D80 vs off-axis angle analysis
+    * Optionally exporting optimized parameters as simulation model files
+
     The assumption are:
 
     a) mirror_align_random_horizontal and mirror_align_random_vertical are the same.
@@ -37,6 +47,8 @@ r"""
         Telescope model name (e.g. LST-1, SST-D, ...).
     model_version (str, optional)
         Model version.
+    parameter_version (str, optional)
+        Parameter version for model parameter file export.
     src_distance (float, optional)
         Source distance in km.
     zenith (float, optional)
@@ -49,6 +61,12 @@ r"""
         Keep the first entry of mirror_reflection_random_angle fixed.
     test (activation mode, optional)
         If activated, application will be faster by simulating fewer photons.
+    write_psf_parameters (activation mode, optional)
+        Write the optimized PSF parameters as simulation model parameter files.
+    random_seed (int, optional)
+        Random seed for parameter generation.
+    n_runs (int, optional)
+        Number of parameter combinations to test.
 
     Example
     -------
@@ -67,58 +85,36 @@ r"""
     .. code-block:: console
 
         simtools-derive-psf-parameters --site North --telescope LSTN-01 \\
-            --model_version 6.0.0 --data PSFcurve_data_v2.txt --plot_all --test
+            --model_version 6.0.0 --data tests/resources/PSFcurve_data_v2.txt --plot_all --test
 
-    The output is saved in simtools-output/derive_psf_parameters.
-
-    Expected final print-out message:
+    Run with parameter export:
 
     .. code-block:: console
 
-        Best parameters:
-        mirror_reflection_random_angle = [0.006, 0.133, 0.005]
-        mirror_align_random_horizontal = [0.005, 28.0, 0.0, 0.0]
-        mirror_align_random_vertical = [0.005, 28.0, 0.0, 0.0]
+        simtools-derive-psf-parameters --site North --telescope LSTN-01 \\
+            --model_version 6.0.0 \\
+            --data tests/resources/PSFcurve_data_v2.txt --write_psf_parameters
+
+    The output is saved in simtools-output/tune_psf.
+
+    Output files include:
+
+    * Parameter optimization results in tested_psf_parameters.txt
+    * PSF comparison plots in tune_psf_[telescope].pdf
+    * D80 vs off-axis angle plots (d80_vs_offaxis_cm.png, d80_vs_offaxis_deg.png)
+    * Optimized simulation model parameter files (if --write_psf_parameters is specified)
+    * Cumulative PSF plots for all tested combinations (if --plot_all is specified)
 
 """
 
 import logging
-from collections import OrderedDict
-
-import astropy.units as u
-import matplotlib.pyplot as plt
-import numpy as np
-from matplotlib.backends.backend_pdf import PdfPages
+from pathlib import Path
 
-import simtools.utils.general as gen
 from simtools.configuration import configurator
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 from simtools.model.model_utils import initialize_simulation_models
-from simtools.ray_tracing.ray_tracing import RayTracing
-from simtools.visualization import visualize
-
-
-def load_data(data_file):
-    """
-    Load data from a text file containing cumulative PSF measurements.
-
-    Parameters
-    ----------
-    data_file : str
-        Name of the data file with the measured cumulative PSF.
-
-    Returns
-    -------
-    numpy.ndarray
-        Loaded and processed data from the file.
-    """
-    radius_cm = "Radius [cm]"
-    cumulative_psf = "Cumulative PSF"
-    d_type = {"names": (radius_cm, cumulative_psf), "formats": ("f8", "f8")}
-    data = np.loadtxt(data_file, dtype=d_type, usecols=(0, 2))
-    data[radius_cm] *= 0.1
-    data[cumulative_psf] /= np.max(np.abs(data[cumulative_psf]))
-    return data
+from simtools.ray_tracing import psf_parameter_optimisation as psf_opt
+from simtools.utils.general import get_log_level_from_user
 
 
 def _parse():
@@ -151,256 +147,37 @@ def _parse():
         help=("Keep the first entry of mirror_reflection_random_angle fixed."),
         action="store_true",
     )
-    return config.initialize(db_config=True, simulation_model=["telescope", "model_version"])
-
-
-def add_parameters(
-    all_parameters,
-    mirror_reflection,
-    mirror_align,
-    mirror_reflection_fraction=0.15,
-    mirror_reflection_2=0.035,
-):
-    """
-    Transform and add parameters to the all_parameters list.
-
-    Parameters
-    ----------
-    mirror_reflection : float
-        The random angle of mirror reflection.
-
-    mirror_align : float
-        The random angle for mirror alignment (both horizontal and vertical).
-
-    mirror_reflection_fraction : float, optional
-        The fraction of the mirror reflection. Default is 0.15.
-
-    mirror_reflection_2 : float, optional
-        A secondary random angle for mirror reflection. Default is 0.035.
-
-    Returns
-    -------
-    None
-        Updates the all_parameters list in place.
-    """
-    # If we want to start from values different than the ones currently in the model:
-    # align = 0.0046
-    # pars_to_change = {
-    #     'mirror_reflection_random_angle': '0.0075 0.125 0.0037',
-    #     'mirror_align_random_horizontal': f'{align} 28 0 0',
-    #     'mirror_align_random_vertical': f'{align} 28 0 0',
-    # }
-    # tel_model.change_multiple_parameters(**pars_to_change)
-    pars = {
-        "mirror_reflection_random_angle": [
-            mirror_reflection,
-            mirror_reflection_fraction,
-            mirror_reflection_2,
-        ],
-        "mirror_align_random_horizontal": [mirror_align, 28.0, 0.0, 0.0],
-        "mirror_align_random_vertical": [mirror_align, 28.0, 0.0, 0.0],
-    }
-    all_parameters.append(pars)
-
-
-def get_previous_values(tel_model, logger):
-    """
-    Retrieve previous parameter values from the telescope model.
-
-    Parameters
-    ----------
-    tel_model : TelescopeModel
-        Telescope model object.
-    logger : logging.Logger
-        Logger object for logging messages.
-
-    Returns
-    -------
-    tuple
-        Tuple containing the previous values of mirror_reflection_random_angle (first entry),
-        mirror_reflection_fraction, second entry), mirror_reflection_random_angle (third entry),
-        and mirror_align_random_horizontal/vertical.
-    """
-    split_par = tel_model.get_parameter_value("mirror_reflection_random_angle")
-    mrra_0, mfr_0, mrra2_0 = split_par[0], split_par[1], split_par[2]
-    mar_0 = tel_model.get_parameter_value("mirror_align_random_horizontal")[0]
-
-    logger.debug(
-        "Previous parameter values:\n"
-        f"MRRA = {mrra_0!s}\n"
-        f"MRF = {mfr_0!s}\n"
-        f"MRRA2 = {mrra2_0!s}\n"
-        f"MAR = {mar_0!s}\n"
+    config.parser.add_argument(
+        "--write_psf_parameters",
+        help=("Write the optimized PSF parameters as simulation model parameter files"),
+        action="store_true",
+        required=False,
     )
-
-    return mrra_0, mfr_0, mrra2_0, mar_0
-
-
-def generate_random_parameters(
-    all_parameters, n_runs, args_dict, mrra_0, mfr_0, mrra2_0, mar_0, logger
-):
-    """
-    Generate random parameters for tuning.
-
-    Parameters
-    ----------
-    all_parameters : list
-        List to store all parameter sets.
-    n_runs : int
-        Number of random parameter combinations to test.
-    args_dict : dict
-        Dictionary containing parsed command-line arguments.
-    mrra_0 : float
-        Initial value of mirror_reflection_random_angle.
-    mfr_0 : float
-        Initial value of mirror_reflection_fraction.
-    mrra2_0 : float
-        Initial value of the second mirror_reflection_random_angle.
-    mar_0 : float
-        Initial value of mirror_align_random_horizontal/vertical.
-    logger : logging.Logger
-        Logger object for logging messages.
-    """
-    # Range around the previous values are hardcoded
-    # Number of runs is hardcoded
-    if args_dict["fixed"]:
-        logger.debug("fixed=True - First entry of mirror_reflection_random_angle is kept fixed.")
-
-    for _ in range(n_runs):
-        mrra_range = 0.004 if not args_dict["fixed"] else 0
-        mrf_range = 0.1
-        mrra2_range = 0.03
-        mar_range = 0.005
-        rng = np.random.default_rng()
-        mrra = rng.uniform(max(mrra_0 - mrra_range, 0), mrra_0 + mrra_range)
-        mrf = rng.uniform(max(mfr_0 - mrf_range, 0), mfr_0 + mrf_range)
-        mrra2 = rng.uniform(max(mrra2_0 - mrra2_range, 0), mrra2_0 + mrra2_range)
-        mar = rng.uniform(max(mar_0 - mar_range, 0), mar_0 + mar_range)
-        add_parameters(all_parameters, mrra, mar, mrf, mrra2)
-
-
-def load_and_process_data(args_dict):
-    """
-    Load and process data if specified in the command-line arguments.
-
-    Returns
-    -------
-    - data_to_plot: OrderedDict containing loaded and processed data.
-    - radius: Radius data from loaded data (if available).
-    """
-    data_to_plot = OrderedDict()
-    radius = None
-
-    if args_dict["data"] is not None:
-        data_file = gen.find_file(args_dict["data"], args_dict["model_path"])
-        data_to_plot["measured"] = load_data(data_file)
-        radius = data_to_plot["measured"]["Radius [cm]"]
-
-    return data_to_plot, radius
-
-
-def calculate_rmsd(data, sim):
-    """Calculate Root Mean Squared Deviation to be used as metric to find the best parameters."""
-    return np.sqrt(np.mean((data - sim) ** 2))
-
-
-def run_pars(tel_model, site_model, args_dict, pars, data_to_plot, radius, pdf_pages):
-    """
-    Run the tuning for one set of parameters, add a plot to the pdfPages and return RMSD and D80.
-
-    Plotting is optional (if plot=True).
-    """
-    cumulative_psf = "Cumulative PSF"
-
-    if pars is not None:
-        tel_model.change_multiple_parameters(**pars)
-    else:
-        raise ValueError("No best parameters found")
-
-    ray = RayTracing(
-        telescope_model=tel_model,
-        site_model=site_model,
-        simtel_path=args_dict["simtel_path"],
-        zenith_angle=args_dict["zenith"] * u.deg,
-        source_distance=args_dict["src_distance"] * u.km,
-        off_axis_angle=[0.0] * u.deg,
+    config.parser.add_argument(
+        "--random_seed",
+        help="Random seed for parameter generation.",
+        type=int,
+        default=None,
     )
-
-    ray.simulate(test=args_dict["test"], force=True)
-    ray.analyze(force=True, use_rx=False)
-
-    # Plotting cumulative PSF
-    im = ray.images()[0]
-    d80 = im.get_psf()
-
-    if radius is not None:
-        # Simulated cumulative PSF
-        data_to_plot["simulated"] = im.get_cumulative_data(radius * u.cm)
-    else:
-        raise ValueError("Radius data is not available.")
-
-    rmsd = calculate_rmsd(
-        data_to_plot["measured"][cumulative_psf], data_to_plot["simulated"][cumulative_psf]
+    config.parser.add_argument(
+        "--n_runs",
+        help="Number of parameter combinations to test.",
+        type=int,
+        default=5,
+    )
+    return config.initialize(
+        db_config=True,
+        simulation_model=["telescope", "model_version", "parameter_version"],
     )
-
-    if args_dict["plot_all"]:
-        fig = visualize.plot_1d(
-            data_to_plot,
-            plot_difference=True,
-            no_markers=True,
-        )
-        ax = fig.get_axes()[0]
-        ax.set_ylim(0, 1.05)
-        ax.set_title(
-            f"refl_rnd={pars['mirror_reflection_random_angle']}, "
-            f"align_rnd={pars['mirror_align_random_vertical']}"
-        )
-
-        ax.text(
-            0.8,
-            0.3,
-            f"D80 = {d80:.3f} cm\nRMSD = {rmsd:.4f}",
-            verticalalignment="center",
-            horizontalalignment="center",
-            transform=ax.transAxes,
-        )
-        plt.tight_layout()
-        pdf_pages.savefig(fig)
-        plt.clf()
-
-    return d80, rmsd
-
-
-def find_best_parameters(
-    all_parameters, tel_model, site_model, args_dict, data_to_plot, radius, pdf_pages
-):
-    """
-    Find the best parameters from all parameter sets.
-
-    Returns
-    -------
-    - Tuple of best parameters and their D80 value.
-    """
-    min_rmsd = 100
-    best_pars = None
-
-    for pars in all_parameters:
-        _, rmsd = run_pars(tel_model, site_model, args_dict, pars, data_to_plot, radius, pdf_pages)
-        if rmsd < min_rmsd:
-            min_rmsd = rmsd
-            best_pars = pars
-
-    return best_pars, min_rmsd
 
 
 def main():  # noqa: D103
     args_dict, db_config = _parse()
 
-    label = "tune_psf"
+    label = label = Path(__file__).stem
     logger = logging.getLogger()
-    logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
+    logger.setLevel(get_log_level_from_user(args_dict["log_level"]))
 
-    # Output directory to save files related directly to this app
     _io_handler = io_handler.IOHandler()
     output_dir = _io_handler.get_output_directory(label, sub_dir="application-plots")
     tel_model, site_model = initialize_simulation_models(
@@ -411,34 +188,7 @@ def main():  # noqa: D103
         model_version=args_dict["model_version"],
     )
 
-    all_parameters = []
-    mrra_0, mfr_0, mrra2_0, mar_0 = get_previous_values(tel_model, logger)
-
-    n_runs = 5 if args_dict["test"] else 50
-    generate_random_parameters(
-        all_parameters, n_runs, args_dict, mrra_0, mfr_0, mrra2_0, mar_0, logger
-    )
-
-    data_to_plot, radius = load_and_process_data(args_dict)
-
-    # Preparing figure name
-    plot_file_name = "_".join((label, tel_model.name + ".pdf"))
-    plot_file = output_dir.joinpath(plot_file_name)
-    pdf_pages = PdfPages(plot_file)
-
-    best_pars, _ = find_best_parameters(
-        all_parameters, tel_model, site_model, args_dict, data_to_plot, radius, pdf_pages
-    )
-
-    # Rerunning and plotting the best pars
-    run_pars(tel_model, site_model, args_dict, best_pars, data_to_plot, radius, pdf_pages)
-    plt.close()
-    pdf_pages.close()
-
-    # Printing the results
-    print("Best parameters:")
-    for par, value in best_pars.items():
-        print(f"{par} = {value}")
+    psf_opt.run_psf_optimization_workflow(tel_model, site_model, args_dict, output_dir)
 
 
 if __name__ == "__main__":

simtools/applications/derive_trigger_rates.py

@@ -0,0 +1,91 @@
+r"""
+Derive cosmic-ray trigger rates for a single telescope or an array of telescopes.
+
+Uses simulated background events (e.g. from proton primaries) to calculate the trigger rates.
+Input is reduced event data generated from simulations for the given configuration.
+
+
+Command line arguments
+----------------------
+event_data_file (str, required)
+    Event data file containing reduced event data.
+array_layout_name (list, optional)
+    Name of the array layout to use for the simulation.
+telescope_ids (str, optional)
+    Path to a file containing telescope configurations.
+plot_histograms (bool, optional)
+    Plot histograms of the event data.
+model_version (str, optional)
+    Version of the simulation model to use.
+site (str, optional)
+    Name of the site where the simulation is being run.
+
+
+Example
+-------
+
+Derive trigger rates for the South Alpha layout:
+
+.. code-block:: console
+
+    simtools-derive-trigger-rates \\
+        --site South \\
+        --model_version 6.0.0 \\
+        --event_data_file /path/to/event_data_file.h5 \\
+        --array_layout_name alpha\\
+        --plot_histograms
+
+"""
+
+import logging
+
+import simtools.utils.general as gen
+from simtools.configuration import configurator
+from simtools.telescope_trigger_rates import telescope_trigger_rates
+
+
+def _parse():
+    """Parse command line configuration."""
+    config = configurator.Configurator(
+        description="Derive trigger rates for a single telescope or an array of telescopes.",
+    )
+    config.parser.add_argument(
+        "--event_data_file",
+        type=str,
+        required=True,
+        help="Event data file containing reduced event data.",
+    )
+    config.parser.add_argument(
+        "--telescope_ids",
+        type=str,
+        required=False,
+        help="Path to a file containing telescope configurations.",
+    )
+    config.parser.add_argument(
+        "--plot_histograms",
+        help="Plot histograms of the event data.",
+        action="store_true",
+        default=False,
+    )
+    return config.initialize(
+        db_config=True,
+        output=True,
+        simulation_model=[
+            "site",
+            "model_version",
+            "layout",
+        ],
+    )
+
+
+def main():  # noqa: D103
+    args_dict, db_config = _parse()
+
+    logger = logging.getLogger()
+    logger.setLevel(gen.get_log_level_from_user(args_dict.get("log_level", "info")))
+
+    telescope_trigger_rates(args_dict, db_config)
+
+
+if __name__ == "__main__":
+    main()

simtools/applications/docs_produce_array_element_report.py

@@ -11,7 +11,7 @@ import logging
 from pathlib import Path
 
 from simtools.configuration import configurator
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 from simtools.reporting.docs_auto_report_generator import ReportGenerator
 from simtools.reporting.docs_read_parameters import ReadParameters
 from simtools.utils import general as gen

simtools/applications/docs_produce_calibration_reports.py

@@ -5,7 +5,7 @@ r"""Produces a markdown file for calibration reports."""
 import logging
 
 from simtools.configuration import configurator
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 from simtools.reporting.docs_read_parameters import ReadParameters
 from simtools.utils import general as gen
 

simtools/applications/docs_produce_model_parameter_reports.py

@@ -11,7 +11,7 @@ Currently only implemented for telescopes.
 import logging
 
 from simtools.configuration import configurator
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 from simtools.reporting.docs_auto_report_generator import ReportGenerator
 from simtools.reporting.docs_read_parameters import ReadParameters
 from simtools.utils import general as gen

simtools/applications/docs_produce_simulation_configuration_report.py

@@ -5,7 +5,7 @@ r"""Produces a markdown file for a given simulation configuration."""
 import logging
 
 from simtools.configuration import configurator
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 from simtools.reporting.docs_read_parameters import ReadParameters
 from simtools.utils import general as gen
 

simtools/applications/generate_corsika_histograms.py

@@ -175,7 +175,7 @@ import simtools.utils.general as gen
 from simtools.configuration import configurator
 from simtools.corsika import corsika_histograms_visualize
 from simtools.corsika.corsika_histograms import CorsikaHistograms
-from simtools.io_operations import io_handler
+from simtools.io import io_handler
 
 logger = logging.getLogger()