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

simtools/testing/sim_telarray_metadata.py

@@ -6,11 +6,11 @@ import numpy as np
 
 from simtools.sim_events.file_info import get_corsika_run_number
 from simtools.simtel.simtel_config_reader import SimtelConfigReader
-from simtools.simtel.simtel_config_writer import sim_telarray_random_seeds
 from simtools.simtel.simtel_io_metadata import (
     get_sim_telarray_telescope_id,
     read_sim_telarray_metadata,
 )
+from simtools.utils import random
 
 _logger = logging.getLogger(__name__)
 
@@ -30,7 +30,7 @@ def assert_sim_telarray_metadata(file, array_model):
     _logger.info(f"Found metadata in sim_telarray file for {len(telescope_meta)} telescopes")
     site_parameter_mismatch = _assert_model_parameters(global_meta, array_model.site_model)
     sim_telarray_seed_mismatch = _assert_sim_telarray_seed(
-        global_meta, array_model.sim_telarray_seeds, file
+        global_meta, array_model.sim_telarray_seed, file
     )
     if sim_telarray_seed_mismatch:
         site_parameter_mismatch.append(sim_telarray_seed_mismatch)
@@ -101,7 +101,7 @@ def _assert_model_parameters(metadata, model):
     return invalid_parameter_list
 
 
-def _assert_sim_telarray_seed(metadata, sim_telarray_seeds, file=None):
+def _assert_sim_telarray_seed(metadata, sim_telarray_seed, file=None):
     """
     Assert that sim_telarray seed matches the values in the sim_telarray metadata.
 
@@ -111,8 +111,8 @@ def _assert_sim_telarray_seed(metadata, sim_telarray_seeds, file=None):
     ----------
     metadata: dict
         Metadata dictionary.
-    sim_telarray_seeds: dict
-        Dictionary of sim_telarray seeds.
+    sim_telarray_seed: SimtelSeeds
+        sim_telarray seed.
     file : Path
         Path to the sim_telarray file.
 
@@ -122,23 +122,25 @@ def _assert_sim_telarray_seed(metadata, sim_telarray_seeds, file=None):
         Error message if sim_telarray seeds do not match.
 
     """
-    if not sim_telarray_seeds or not metadata:
+    if sim_telarray_seed is None:
         return None
 
     if "instrument_seed" in metadata.keys() and "instrument_instances" in metadata.keys():
-        if str(metadata.get("instrument_seed")) != str(sim_telarray_seeds.get("seed")):
+        if str(metadata.get("instrument_seed")) != str(sim_telarray_seed.instrument_seed):
             return (
                 "Parameter instrument_seed mismatch between sim_telarray file: "
-                f"{metadata['instrument_seed']}, and model: {sim_telarray_seeds.get('seed')}"
+                f"{metadata['instrument_seed']}, and model: {sim_telarray_seed.instrument_seed}"
             )
         _logger.info(
             f"sim_telarray_seed in sim_telarray file: {metadata['instrument_seed']}, "
-            f"and model: {sim_telarray_seeds.get('seed')}"
+            f"and model: {sim_telarray_seed.instrument_seed}"
         )
         if file:
             run_number_modified = get_corsika_run_number(file) - 1
-            test_seeds = sim_telarray_random_seeds(
-                int(metadata["instrument_seed"]), int(metadata["instrument_instances"])
+            test_seeds = random.seeds(
+                n_seeds=int(metadata["instrument_instances"]),
+                max_seed=np.iinfo(np.int32).max,
+                fixed_seed=int(metadata["instrument_seed"]),
             )
             # no +1 as in sim_telarray (as we count from 0)
             seed_used = run_number_modified % int(metadata["instrument_instances"])

simtools/testing/validate_output.py

@@ -46,7 +46,7 @@ def validate_application_output(config, from_command_line=None, from_config_file
     """
     Validate application output against expected output.
 
-    Expected output is defined in configuration file.
+    Expected output is defined in the test configuration file.
     Some tests run only if the model version from the command line
     equals the model version from the configuration file.
 
@@ -88,6 +88,8 @@ def _validate_output_files(config, integration_test):
     if "reference_output_file" in integration_test:
         _validate_reference_output_file(config, integration_test)
     if "test_output_files" in integration_test:
+        if isinstance(integration_test["test_output_files"], dict):
+            integration_test["test_output_files"] = [integration_test["test_output_files"]]
         _validate_output_path_and_file(config, integration_test["test_output_files"])
     if "output_file" in integration_test:
         _validate_output_path_and_file(
@@ -116,11 +118,10 @@ def _test_simtel_cfg_files(config, integration_test, from_command_line, from_con
 
 def _validate_reference_output_file(config, integration_test):
     """Compare with reference output file."""
+    test_file = integration_test.get("test_output_file") or config["configuration"]["output_file"]
     assert compare_files(
         integration_test["reference_output_file"],
-        Path(config["configuration"]["output_path"]).joinpath(
-            config["configuration"]["output_file"]
-        ),
+        Path(config["configuration"]["output_path"]).joinpath(test_file),
         integration_test.get("tolerance", 1.0e-5),
         integration_test.get("test_columns", None),
     )
@@ -189,6 +190,7 @@ def _validate_model_parameter_json_file(config, model_parameter_validation):
         model_parameter["value"],
         reference_model_parameter[reference_parameter_name]["value"],
         model_parameter_validation["tolerance"],
+        model_parameter_validation.get("scaling", 1.0),
     )
 
 
@@ -227,12 +229,56 @@ def compare_files(file1, file2, tolerance=1.0e-5, test_columns=None):
     return False
 
 
+def _compare_nested_dicts_with_tolerance(data1, data2, tolerance, is_value_field=False):
+    """
+    Recursively compare nested dictionaries, applying allclose to "value" fields.
+
+    Parameters
+    ----------
+    data1 : dict, list, or scalar
+        First data to compare
+    data2 : dict, list, or scalar
+        Second data to compare
+    tolerance : float
+        Tolerance for comparing numerical values
+    is_value_field : bool
+        Whether this data is from a "value" key (applies tolerance to scalars)
+
+    Returns
+    -------
+    bool
+        True if the data are equal within tolerance
+    """
+    if isinstance(data1, dict) and isinstance(data2, dict):
+        return data1.keys() == data2.keys() and all(
+            _compare_nested_dicts_with_tolerance(
+                data1[k], data2[k], tolerance, is_value_field=(k == "value")
+            )
+            for k in data1
+        )
+
+    if isinstance(data1, (list, tuple)) and isinstance(data2, (list, tuple)):
+        return len(data1) == len(data2) and all(
+            _compare_nested_dicts_with_tolerance(v1, v2, tolerance, is_value_field)
+            for v1, v2 in zip(data1, data2)
+        )
+
+    # Apply tolerance if this is a "value" field, otherwise use exact equality
+    if is_value_field:
+        try:
+            return _compare_value_from_parameter_dict(data1, data2, tolerance)
+        except (TypeError, ValueError):
+            return data1 == data2
+    return data1 == data2
+
+
 def compare_json_or_yaml_files(file1, file2, tolerance=1.0e-2):
     """
     Compare two json or yaml files.
 
     Take into account float comparison for sim_telarray string-embedded floats.
     Allow differences in 'schema_version' field.
+    Works recursively for nested dicts with "value" fields on any level.
 
     Parameters
     ----------
@@ -259,24 +305,45 @@ def compare_json_or_yaml_files(file1, file2, tolerance=1.0e-2):
     if data1 == data2:
         return True
 
-    if data1.keys() != data2.keys():
-        _logger.error(f"Keys do not match: {data1.keys()} and {data2.keys()}")
-        return False
-    _comparison = all(
-        (
-            _compare_value_from_parameter_dict(data1[k], data2[k], tolerance)
-            if k == "value"
-            else data1[k] == data2[k]
-        )
-        for k in data1
+    if isinstance(data1, dict) and isinstance(data2, dict):
+        if data1.keys() != data2.keys():
+            _logger.error(f"Keys do not match: {data1.keys()} and {data2.keys()}")
+            return False
+
+    _comparison = _compare_nested_dicts_with_tolerance(
+        data1, data2, tolerance, is_value_field=False
     )
     if not _comparison:
         _logger.error(f"Values do not match: {data1} and {data2} (tolerance: {tolerance})")
     return _comparison
 
 
-def _compare_value_from_parameter_dict(data1, data2, tolerance=1.0e-5):
-    """Compare value fields given in different formats."""
+def _compare_value_from_parameter_dict(data_1, data_2, tolerance=1.0e-5, factor_1=1.0):
+    """
+    Compare value fields given in different formats.
+
+    Parameters
+    ----------
+    data_1 : float, int, str, list, numpy.ndarray
+        First value or collection of values to compare. May be a scalar,
+        a sequence, a numpy array, or a string representation of a list.
+    data_2 : float, int, str, list, numpy.ndarray
+        Second value or collection of values to compare, with the same
+        allowed formats as ``data_2``.
+    tolerance : float, optional
+        Relative tolerance used when comparing numerical values via
+        ``numpy.allclose``.
+    factor1 : float, optional
+        Multiplicative factor applied to ``data_1`` before comparison. This
+        can be used to account for unit conversions or normalisation
+        differences between ``data_1`` and ``data_2``.
+
+    Returns
+    -------
+    bool
+        True if the two values are considered equal within the given
+        tolerance, False otherwise.
+    """
 
     def _as_list(value):
         if isinstance(value, str):
@@ -285,12 +352,13 @@ def _compare_value_from_parameter_dict(data1, data2, tolerance=1.0e-5):
             return value
         return [value]
 
-    _logger.info(f"Comparing values: {data1} and {data2} (tolerance: {tolerance})")
+    _logger.info(f"Comparing values: {data_1} and {data_2} (tolerance: {tolerance})")
 
-    _as_list_1 = _as_list(data1)
-    _as_list_2 = _as_list(data2)
+    _as_list_1 = _as_list(data_1)
+    _as_list_2 = _as_list(data_2)
     if isinstance(_as_list_1, str):
         return _as_list_1 == _as_list_2
+    _as_list_1 = np.array(_as_list_1) * factor_1
     return np.allclose(_as_list_1, _as_list_2, rtol=tolerance)
 
 

simtools/utils/general.py

@@ -582,6 +582,12 @@ def validate_data_type(reference_dtype, value=None, dtype=None, allow_subtypes=T
     if reference_dtype in ("boolean", "bool"):
         return _is_valid_boolean_type(dtype, value)
 
+    if reference_dtype == "dict":
+        return isinstance(value, dict)
+
+    if reference_dtype == "list":
+        return isinstance(value, list)
+
     return _is_valid_numeric_type(dtype, reference_dtype)
 
 
@@ -796,23 +802,6 @@ def find_differences_in_json_objects(obj1, obj2, path=""):
     return diffs
 
 
-def clear_default_sim_telarray_cfg_directories(command):
-    """Prefix the command to clear default sim_telarray configuration directories.
-
-    Parameters
-    ----------
-    command: str
-        Command to be prefixed.
-
-    Returns
-    -------
-    str
-        Prefixed command.
-
-    """
-    return f"SIM_TELARRAY_CONFIG_PATH='' {command}"
-
-
 def get_list_of_files_from_command_line(file_names, suffix_list):
     """
     Get a list of files from the command line.

simtools/utils/random.py

@@ -0,0 +1,36 @@
+"""Random numbers utilities."""
+
+import secrets
+
+import numpy as np
+
+
+def seeds(n_seeds=1, min_seed=1, max_seed=2_000_000_000, fixed_seed=None):
+    """
+    Generate independent random seeds.
+
+    Parameters
+    ----------
+    n_seeds : int
+        Number of seeds to generate.
+    min_seed : int
+        Lower limit for the seed (inclusive).
+    max_seed : int
+        Upper limit for the seed (exclusive).
+    fixed_seed : int or None
+        If provided, use this fixed seed.
+
+    Returns
+    -------
+    int or list of int:
+        A single seed if n_seeds is 1, otherwise a list of seeds.
+    """
+    entropy = fixed_seed if fixed_seed is not None else secrets.randbits(128)
+    ss = np.random.SeedSequence(entropy)
+    rng = np.random.default_rng(ss)
+
+    seed_list = rng.integers(low=min_seed, high=max_seed, size=n_seeds)
+
+    if n_seeds == 1:
+        return int(seed_list[0])
+    return [int(x) for x in seed_list]

simtools/visualization/plot_corsika_histograms.py

@@ -149,6 +149,8 @@ def _plot_1d(hist_list, labels=None):
     ax.set_xlabel(_get_axis_label(hist["x_axis_title"], hist["x_axis_unit"]))
     ax.set_ylabel(_get_axis_label(hist["y_axis_title"], hist["y_axis_unit"]))
     _configure_plot_scales(ax, hist)
+    if "y_axis_min" in hist and hist["y_axis_min"] is not None:
+        ax.set_ylim(bottom=float(hist["y_axis_min"]))
     ax.set_title(f"{hist['title']}")
     ax.legend()
     ax.grid(True, alpha=0.3)

simtools/visualization/plot_incident_angles.py

@@ -351,6 +351,7 @@ def _plot_component_angles(
     out_path,
     bin_width_deg,
     log,
+    model_version=None,
 ):
     arrays = _gather_angle_arrays(results_by_offset, column, log)
     if not arrays:
@@ -365,6 +366,17 @@ def _plot_component_angles(
     ax.set_title(f"Incident angle {title_suffix} vs off-axis angle")
     ax.grid(True, alpha=0.3)
     ax.legend()
+    if model_version:
+        ax.text(
+            0.03,
+            0.97,
+            f"Model version: {model_version}",
+            transform=ax.transAxes,
+            fontsize=8,
+            verticalalignment="top",
+            horizontalalignment="left",
+            bbox={"boxstyle": "round", "facecolor": "white", "alpha": 0.5},
+        )
     plt.tight_layout()
     plt.savefig(out_path, dpi=300)
     plt.close(fig)
@@ -378,8 +390,30 @@ def plot_incident_angles(
     radius_bin_width_m=0.01,
     debug_plots=False,
     logger=None,
+    model_version=None,
 ):
-    """Plot overlaid histograms of focal, primary, secondary angles, and primary hit radius."""
+    """Plot overlaid histograms of focal, primary, secondary angles, and primary hit radius.
+
+    Parameters
+    ----------
+    results_by_offset : dict
+        Mapping from off-axis angle to result tables containing angle and radius columns.
+    output_dir : path-like
+        Base output directory where the ``plots`` subdirectory will be created.
+    label : str
+        Label used to distinguish this set of plots in the output filenames.
+    bin_width_deg : float, optional
+        Bin width in degrees for the angle-of-incidence histograms.
+    radius_bin_width_m : float, optional
+        Bin width in meters for the primary mirror hit-radius histograms.
+    debug_plots : bool, optional
+        If True, generate additional diagnostic plots.
+    logger : logging.Logger or None, optional
+        Logger instance to use for messages. If None, a module-level logger is used.
+    model_version : str or None, optional
+        Semantic model version identifier to annotate the generated plots. If None,
+        no model version text is added to the figures.
+    """
     log = logger or logging.getLogger(__name__)
     if not results_by_offset:
         log.warning("No results provided for multi-offset plot")
@@ -402,6 +436,17 @@ def plot_incident_angles(
             ax.set_title("Incident angle distribution vs off-axis angle")
             ax.grid(True, alpha=0.3)
             ax.legend()
+            if model_version:
+                ax.text(
+                    0.03,
+                    0.97,
+                    f"Model version: {model_version}",
+                    transform=ax.transAxes,
+                    fontsize=8,
+                    verticalalignment="top",
+                    horizontalalignment="left",
+                    bbox={"boxstyle": "round", "facecolor": "white", "alpha": 0.5},
+                )
             plt.tight_layout()
             plt.savefig(out_dir / f"incident_angles_multi_{label}.png", dpi=300)
             plt.close(fig)
@@ -414,6 +459,7 @@ def plot_incident_angles(
         out_path=out_dir / f"incident_angles_primary_multi_{label}.png",
         bin_width_deg=bin_width_deg,
         log=log,
+        model_version=model_version,
     )
     _plot_component_angles(
         results_by_offset=results_by_offset,
@@ -422,6 +468,7 @@ def plot_incident_angles(
         out_path=out_dir / f"incident_angles_secondary_multi_{label}.png",
         bin_width_deg=bin_width_deg,
         log=log,
+        model_version=model_version,
     )
 
     # Debug plots

simtools/visualization/plot_psf.py

@@ -6,6 +6,7 @@ including parameter comparison plots, convergence plots, and PSF diameter vs off
 """
 
 import logging
+from pathlib import Path
 
 import astropy.units as u
 import matplotlib.pyplot as plt
@@ -141,22 +142,27 @@ def _create_base_plot_figure(data_to_plot, simulated_data=None):
 
 
 def _build_parameter_title(pars, is_best):
-    """Build parameter title string for plots."""
+    """Build parameter title string for plots, handling optional parameter groups."""
     title_prefix = "* " if is_best else ""
-    return (
-        f"{title_prefix}reflection = "
-        f"{pars['mirror_reflection_random_angle'][0]:.5f}, "
-        f"{pars['mirror_reflection_random_angle'][1]:.5f}, "
-        f"{pars['mirror_reflection_random_angle'][2]:.5f}\n"
-        f"align_vertical = {pars['mirror_align_random_vertical'][0]:.5f}, "
-        f"{pars['mirror_align_random_vertical'][1]:.5f}, "
-        f"{pars['mirror_align_random_vertical'][2]:.5f}, "
-        f"{pars['mirror_align_random_vertical'][3]:.5f}\n"
-        f"align_horizontal = {pars['mirror_align_random_horizontal'][0]:.5f}, "
-        f"{pars['mirror_align_random_horizontal'][1]:.5f}, "
-        f"{pars['mirror_align_random_horizontal'][2]:.5f}, "
-        f"{pars['mirror_align_random_horizontal'][3]:.5f}"
-    )
+    title_lines = []
+
+    if "mirror_reflection_random_angle" in pars:
+        refl = pars["mirror_reflection_random_angle"]
+        title_lines.append(f"reflection = {refl[0]:.5f}, {refl[1]:.5f}, {refl[2]:.5f}")
+
+    if "mirror_align_random_vertical" in pars:
+        vert = pars["mirror_align_random_vertical"]
+        title_lines.append(
+            f"align_vertical = {vert[0]:.5f}, {vert[1]:.5f}, {vert[2]:.5f}, {vert[3]:.5f}"
+        )
+
+    if "mirror_align_random_horizontal" in pars:
+        horiz = pars["mirror_align_random_horizontal"]
+        title_lines.append(
+            f"align_horizontal = {horiz[0]:.5f}, {horiz[1]:.5f}, {horiz[2]:.5f}, {horiz[3]:.5f}"
+        )
+
+    return title_prefix + "\n".join(title_lines)
 
 
 def _add_metric_text_box(ax, metrics_text, is_best):
@@ -640,7 +646,7 @@ def create_psf_vs_offaxis_plot(tel_model, site_model, args_dict, best_pars, outp
     logger.info(f"Creating {psf_label_cm} vs off-axis angle plot with best parameters...")
 
     # Apply best parameters to telescope model
-    tel_model.overwrite_parameters(best_pars)
+    tel_model.overwrite_parameters(best_pars, flat_dict=True)
 
     # Create off-axis angle array
     max_offset = args_dict.get("max_offset", MAX_OFFSET_DEFAULT)
@@ -654,6 +660,7 @@ def create_psf_vs_offaxis_plot(tel_model, site_model, args_dict, best_pars, outp
     ray = RayTracing(
         telescope_model=tel_model,
         site_model=site_model,
+        label=args_dict.get("label") or getattr(tel_model, "label", None),
         zenith_angle=args_dict["zenith"] * u.deg,
         source_distance=args_dict["src_distance"] * u.km,
         off_axis_angle=off_axis_angles * u.deg,
@@ -661,9 +668,9 @@ def create_psf_vs_offaxis_plot(tel_model, site_model, args_dict, best_pars, outp
 
     logger.info(f"Running ray tracing for {len(off_axis_angles)} off-axis angles...")
     ray.simulate(test=args_dict.get("test", False), force=True)
-    ray.analyze(force=True)
+    ray.analyze(force=True, containment_fraction=fraction)
 
-    for key in ["d80_cm", "d80_deg"]:
+    for key in ["psf_cm", "psf_deg"]:
         plt.figure(figsize=(10, 6), tight_layout=True)
 
         ray.plot(key, marker="o", linestyle="-", color="blue", linewidth=2, markersize=6)
@@ -772,3 +779,138 @@ def create_optimization_plots(args_dict, gd_results, tel_model, data_to_plot, ou
                 use_ks_statistic=False,
             )
     pdf_pages.close()
+
+
+def create_summary_psf_comparison_plot(
+    tel_model, optimized_params, data_to_plot, output_dir, final_rmsd, simulated_data
+):
+    """
+    Create a standalone plot comparing measured vs simulated PSF with final optimized parameters.
+
+    This creates a single plot showing the cumulative PSF comparison
+    before and after the optimization.
+
+    Parameters
+    ----------
+    tel_model : TelescopeModel
+        Telescope model with optimized parameters
+    optimized_params : dict
+        Dictionary of optimized parameter values
+    data_to_plot : dict
+        Measured PSF data
+    output_dir : Path
+        Directory for output files
+    final_rmsd : float
+        Final RMSD value at the end of optimization
+    simulated_data : dict
+        Final simulated PSF data with optimized parameters
+
+    Returns
+    -------
+    Path
+        Path to the created plot file
+    """
+    fig, ax = _create_base_plot_figure(data_to_plot, simulated_data)
+
+    title_lines = ["Final Optimized Parameters:"]
+    if "mirror_reflection_random_angle" in optimized_params:
+        refl = optimized_params["mirror_reflection_random_angle"]
+        title_lines.append(
+            f"mirror_reflection_random_angle = [{refl[0]:.6f}, {refl[1]:.6f}, {refl[2]:.6f}]"
+        )
+
+    if "mirror_align_random_vertical" in optimized_params:
+        vert = optimized_params["mirror_align_random_vertical"]
+        title_lines.append(
+            f"mirror_align_random_vertical = "
+            f"[{vert[0]:.6f}, {vert[1]:.6f}, {vert[2]:.6f}, {vert[3]:.6f}]"
+        )
+
+    if "mirror_align_random_horizontal" in optimized_params:
+        horiz = optimized_params["mirror_align_random_horizontal"]
+        title_lines.append(
+            f"mirror_align_random_horizontal = "
+            f"[{horiz[0]:.6f}, {horiz[1]:.6f}, {horiz[2]:.6f}, {horiz[3]:.6f}]"
+        )
+
+    ax.set_title("\n".join(title_lines), fontsize=9, loc="left")
+
+    rmsd_text = f"RMSD = {final_rmsd:.4f} ({final_rmsd * 100:.2f}%)"
+    ax.text(
+        0.98,
+        0.02,
+        rmsd_text,
+        transform=ax.transAxes,
+        fontsize=12,
+        verticalalignment="bottom",
+        horizontalalignment="right",
+        bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.8},
+    )
+
+    output_file = Path(output_dir) / f"{tel_model.name}_final_psf_comparison.png"
+    fig.savefig(output_file, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+    logger.info(f"Final PSF comparison plot saved to {output_file}")
+    return output_file
+
+
+def plot_psf_histogram(measured, simulated, args_dict):
+    """Write histogram comparing measured vs simulated PSF diameter distributions."""
+    output_dir = Path(args_dict.get("output_path", "."))
+    out_name = args_dict.get("psf_hist")
+    if not out_name:
+        return None
+    out_path = Path(out_name)
+    if not out_path.is_absolute():
+        out_path = output_dir / out_path
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    measured = np.asarray(measured, dtype=float)
+    simulated = np.asarray(simulated, dtype=float)
+    measured = measured[np.isfinite(measured)]
+    simulated = simulated[np.isfinite(simulated)]
+    if measured.size == 0 or simulated.size == 0:
+        return None
+    bins = 25
+    all_vals = np.concatenate([measured, simulated])
+    x_min = float(np.nanmin(all_vals))
+    x_max = float(np.nanmax(all_vals))
+    if not np.isfinite(x_min) or not np.isfinite(x_max) or x_max <= x_min:
+        return None
+    bin_edges = np.linspace(x_min, x_max, bins + 1)
+    meas_mean = float(np.mean(measured))
+    meas_rms = float(np.std(measured, ddof=0))
+    sim_mean = float(np.mean(simulated))
+    sim_rms = float(np.std(simulated, ddof=0))
+    fig, ax = plt.subplots(figsize=(7.5, 4.5), constrained_layout=True)
+    ax.hist(
+        measured,
+        bins=bin_edges,
+        alpha=0.55,
+        color="tab:red",
+        edgecolor="white",
+        label=f"Measured (mean={meas_mean:.2f} mm, rms={meas_rms:.2f} mm)",
+    )
+    ax.hist(
+        simulated,
+        bins=bin_edges,
+        alpha=0.55,
+        color="tab:blue",
+        edgecolor="white",
+        label=f"Simulated (mean={sim_mean:.2f} mm, rms={sim_rms:.2f} mm)",
+    )
+    ax.axvline(meas_mean, color="tab:red", linestyle="--", linewidth=1)
+    ax.axvline(sim_mean, color="tab:blue", linestyle="--", linewidth=1)
+    tel = args_dict.get("telescope", "")
+    model_version = args_dict.get("model_version", "")
+    fraction = args_dict.get("fraction")
+    label = get_psf_diameter_label(fraction, unit="mm") if fraction is not None else "PSF"
+    suffix = " ".join([s for s in (tel, model_version) if s])
+    ax.set_xlabel(label)
+    ax.set_ylabel("Count")
+    ax.set_title(f"{label} ({suffix})" if suffix else label)
+    ax.legend(loc="best", fontsize=9, frameon=True)
+    fig.savefig(out_path)
+    plt.close(fig)
+    logger.info("PSF histogram written to %s", str(out_path))
+    return str(out_path)