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

simtools/atmosphere.py

@@ -0,0 +1,83 @@
+"""Profiles of atmospheric parameters as a function of altitude."""
+
+import logging
+from pathlib import Path
+
+import astropy.units as u
+import numpy as np
+
+
+class AtmosphereProfile:
+    """
+    Profiles of atmospheric parameters as a function of altitude.
+
+    Parameters
+    ----------
+    filename: str or Path
+        Path to the atmosphere profile file (CORSIKA table format)
+    """
+
+    def __init__(self, filename):
+        """AtmosphereProfile initialization."""
+        self._logger = logging.getLogger(__name__)
+        self.columns = {}
+        self.read_atmosphere_profile(filename)
+
+    def read_atmosphere_profile(self, filename):
+        """
+        Read atmosphere profile from file.
+
+        Parameters
+        ----------
+        filename: str or Path
+            Path to the atmosphere profile file (CORSIKA table format)
+
+        """
+        filename = Path(filename)
+        data = []
+        self._logger.debug(f"Reading atmosphere profile from {filename}")
+        with filename.open(encoding="utf-8") as f:
+            for line in f:
+                if not line.strip() or line.lstrip().startswith("#"):
+                    continue
+                data.append([float(x) for x in line.split()])
+
+        self.data = np.array(data)
+        self.columns = {
+            "alt": 0,
+            "rho": 1,
+            "thick": 2,
+            "n_minus_1": 3,
+            "T": 4,
+            "p": 5,
+            "pw_over_p": 6,
+        }
+
+    def interpolate(self, altitude, column="thick"):
+        """
+        Interpolate the atmosphere profile at a given altitude.
+
+        Parameters
+        ----------
+        altitude: astropy.units.Quantity
+            Altitude
+        column: str
+            Column name to interpolate.
+
+        Returns
+        -------
+        float
+            Interpolated value.
+        """
+        if column not in self.columns:
+            raise KeyError(f"Unknown column: {column}")
+
+        altitude = altitude.to(u.km).value
+
+        x = self.data[:, 0]
+        y = self.data[:, self.columns[column]]
+
+        if altitude < x.min() or altitude > x.max():
+            raise ValueError("Altitude out of bounds")
+
+        return np.interp(altitude, x, y)

simtools/camera/camera_efficiency.py

@@ -3,13 +3,17 @@
 import logging
 import re
 from collections import defaultdict
+from pathlib import Path
 
 import astropy.io.ascii
 import astropy.units as u
 import numpy as np
 from astropy.table import Table
 
-from simtools.io import io_handler
+import simtools.data_model.model_data_writer as writer
+from simtools import settings
+from simtools.atmosphere import AtmosphereProfile
+from simtools.io import ascii_handler, io_handler
 from simtools.model.model_utils import initialize_simulation_models
 from simtools.simtel.simulator_camera_efficiency import SimulatorCameraEfficiency
 from simtools.utils import names
@@ -22,25 +26,23 @@ class CameraEfficiency:
 
     Parameters
     ----------
-    db_config: dict
-        Configuration for the database.
     label: str
         Instance label, optional.
     config_data: dict.
         Dict containing the configurable parameters.
+    efficiency_type: str
+        The type of efficiency to simulate (e.g., 'Shower', 'Muon', or 'NSB').
     """
 
-    def __init__(self, config_data, label, db_config):
+    def __init__(self, label, config_data, efficiency_type):
         """Initialize the CameraEfficiency class."""
         self._logger = logging.getLogger(__name__)
 
-        self._simtel_path = config_data.get("simtel_path")
         self.label = label
 
         self.io_handler = io_handler.IOHandler()
         self.telescope_model, self.site_model, _ = initialize_simulation_models(
             label=self.label,
-            db_config=db_config,
             model_version=config_data["model_version"],
             site=config_data["site"],
             telescope_name=config_data["telescope"],
@@ -49,8 +51,9 @@ class CameraEfficiency:
 
         self._results = None
         self._has_results = False
+        self.efficiency_type = efficiency_type.lower()
 
-        self.config = self._configuration_from_args_dict(config_data)
+        self.config = self._configuration(config_data)
         self._file = self._load_files()
 
         self.nsb_pixel_pe_per_ns = None
@@ -60,9 +63,9 @@ class CameraEfficiency:
         """Return string representation of the CameraEfficiency instance."""
         return f"CameraEfficiency(label={self.label})\n"
 
-    def _configuration_from_args_dict(self, config_data):
+    def _configuration(self, config_data):
         """
-        Extract configuration data from command line arguments.
+        Extract configuration data from command line and class parameters.
 
         Parameters
         ----------
@@ -78,6 +81,7 @@ class CameraEfficiency:
             "zenith_angle": config_data["zenith_angle"].to("deg").value,
             "azimuth_angle": config_data["azimuth_angle"].to("deg").value,
             "nsb_spectrum": config_data.get("nsb_spectrum", None),
+            "efficiency_type": self.efficiency_type,
         }
 
     def _load_files(self):
@@ -88,15 +92,13 @@ class CameraEfficiency:
             [".ecsv", ".dat", ".log"],
         ):
             file_name = names.generate_file_name(
-                file_type=(
-                    "camera_efficiency_table" if label == "results" else "camera_efficiency"
-                ),
+                file_type="camera_efficiency",
                 suffix=suffix,
                 site=self.telescope_model.site,
                 telescope_model_name=self.telescope_model.name,
                 zenith_angle=self.config["zenith_angle"],
                 azimuth_angle=self.config["azimuth_angle"],
-                label=self.label,
+                label=self.efficiency_type,
             )
 
             _file[label] = self.io_handler.get_output_directory().joinpath(file_name)
@@ -109,13 +111,13 @@ class CameraEfficiency:
         self.export_model_files()
 
         simtel = SimulatorCameraEfficiency(
-            simtel_path=self._simtel_path,
             telescope_model=self.telescope_model,
             site_model=self.site_model,
             zenith_angle=self.config["zenith_angle"],
             file_simtel=self._file["sim_telarray"],
             file_log=self._file["log"],
             label=self.label,
+            x_max=self._get_x_max_for_efficiency_type(),
             nsb_spectrum=self.config["nsb_spectrum"],
             skip_correction_to_nsb_spectrum=self.config.get(
                 "skip_correction_to_nsb_spectrum", False
@@ -250,34 +252,78 @@ class CameraEfficiency:
 
     def results_summary(self):
         """
-        Print a summary of the results.
+        Fill a dictionary with summary of the results.
 
         Include a header for the zenith/azimuth settings and the NSB spectrum file which was used.
         The summary includes the various CTAO requirements and the final expected NSB pixel rate.
+
+        Returns
+        -------
+        dict
+            Summary of the results.
         """
-        nsb_spectrum_text = (
-            f"NSB spectrum file: {self.config['nsb_spectrum']}"
-            if self.config["nsb_spectrum"]
-            else "default sim_telarray spectrum."
-        )
-        return (
-            f"Results summary for {self.telescope_model.name} at "
-            f"zenith={self.config['zenith_angle']:.1f} deg, "
-            f"azimuth={self.config['azimuth_angle']:.1f} deg\n"
-            f"Using the {nsb_spectrum_text}\n"
-            f"\nSpectrum weighted reflectivity: {self.calc_reflectivity():.4f}\n"
-            "Camera nominal efficiency with gaps (B-TEL-1170): "
-            f"{self.calc_camera_efficiency():.4f}\n"
-            "Telescope total efficiency"
-            f" with gaps (was A-PERF-2020): {self.calc_tel_efficiency():.4f}\n"
-            "Telescope total Cherenkov light efficiency / sqrt(total NSB efficiency) "
-            "(A-PERF-2025/B-TEL-0090): "
-            f"{self.calc_tot_efficiency(self.calc_tel_efficiency()):.4f}\n"
-            "Expected NSB pixel rate for the provided NSB spectrum: "
-            f"{self.nsb_pixel_pe_per_ns:.4f} [p.e./ns]\n"
-            "Expected NSB pixel rate for the reference NSB: "
-            f"{self.nsb_rate_ref_conditions:.4f} [p.e./ns]\n"
-        )
+        meta = {
+            "meta": {
+                "tel": self.telescope_model.name,
+                "model_version": self.telescope_model.model_version,
+                "zen": self.config["zenith_angle"],
+                "az": self.config["azimuth_angle"],
+                "nsb": (
+                    self.config["nsb_spectrum"]
+                    if self.config["nsb_spectrum"]
+                    else "default sim_telarray spectrum"
+                ),
+            }
+        }
+
+        metrics = {}
+        if self.efficiency_type == "shower":
+            metrics |= {
+                "reflectivity": {
+                    "value": self.calc_reflectivity(),
+                    "description": "Spectrum weighted reflectivity",
+                },
+                "cam_eff": {
+                    "value": self.calc_camera_efficiency(),
+                    "description": "Camera nominal efficiency with gaps (B-TEL-1170)",
+                },
+                "tel_eff": {
+                    "value": self.calc_tel_efficiency(),
+                    "description": "Telescope total efficiency with gaps (was A-PERF-2020)",
+                },
+                "tot_sens": {
+                    "value": self.calc_tot_efficiency(self.calc_tel_efficiency()),
+                    "description": (
+                        "Telescope total Cherenkov light efficiency / sqrt(total NSB efficiency) "
+                        "(A-PERF-2025/B-TEL-0090)"
+                    ),
+                },
+            }
+
+        elif self.efficiency_type == "nsb":
+            metrics |= {
+                "nsb_rate": {
+                    "value": self.nsb_pixel_pe_per_ns,
+                    "description": "Expected NSB pixel rate for the provided NSB spectrum",
+                },
+                "nsb_ref": {
+                    "value": self.nsb_rate_ref_conditions,
+                    "description": "Expected NSB pixel rate for the reference NSB",
+                },
+            }
+
+        elif self.efficiency_type == "muon":
+            metrics |= {
+                "muon_frac": {
+                    "value": self.calc_partial_efficiency(lambda_min=200.0, lambda_max=290.0),
+                    "description": (
+                        "Fraction of light (from muons) in the wavelength range 200-290 nm "
+                        "(B-TEL-0095)"
+                    ),
+                },
+            }
+
+        return meta | metrics
 
     def export_results(self):
         """Export results to a ecsv file."""
@@ -288,12 +334,9 @@ class CameraEfficiency:
             astropy.io.ascii.write(
                 self._results, self._file["results"], format="basic", overwrite=True
             )
-            _results_summary_file = (
-                str(self._file["results"]).replace(".ecsv", ".txt").replace("_table_", "_summary_")
-            )
+            _results_summary_file = str(self._file["results"]).replace(".ecsv", "_summary.yml")
             self._logger.info(f"Exporting summary results to {_results_summary_file}")
-            with open(_results_summary_file, "w", encoding="utf-8") as file:
-                file.write(self.results_summary())
+            ascii_handler.write_data_to_file(self.results_summary(), Path(_results_summary_file))
 
     def _read_results(self):
         """Read existing results file and store it in _results."""
@@ -368,6 +411,39 @@ class CameraEfficiency:
 
         return tel_efficiency / np.sqrt(tel_efficiency_nsb)
 
+    def calc_partial_efficiency(self, lambda_min=200.0, lambda_max=290.0):
+        """
+        Compare efficiency in a given wavelength range with total efficiency.
+
+        Parameters
+        ----------
+        lambda_min: float
+            Minimum wavelength in nm.
+        lambda_max: float
+            Maximum wavelength in nm.
+
+        Returns
+        -------
+        Float
+            Fraction of light in the given wavelength range compared to total efficiency.
+
+        """
+        # Sum(C4) from lamba_min to lambda_max nm:
+        c4_reduced_wl = self._results["C4"][
+            [lambda_min < wl_now < lambda_max for wl_now in self._results["wl"]]
+        ]
+        c4_sum = np.sum(c4_reduced_wl)
+        # Sum(C4) from 200 - 999 nm:
+        c4_sum_total = np.sum(self._results["C4"])
+        # (no need to apply masts or fill factors as in calc_tel_efficiency, they cancel out)
+
+        self._logger.info(
+            f"Fraction of light in the wavelength range {lambda_min}-{lambda_max} nm: "
+            f"{c4_sum / c4_sum_total:.4f}"
+        )
+
+        return c4_sum / c4_sum_total
+
     def calc_reflectivity(self):
         """
         Calculate the Cherenkov spectrum weighted reflectivity in the range 300-550 nm.
@@ -433,14 +509,12 @@ class CameraEfficiency:
         )
         return self.nsb_pixel_pe_per_ns * u.GHz, self.nsb_rate_ref_conditions * u.GHz
 
-    def plot_efficiency(self, efficiency_type, save_fig=False):
+    def plot_efficiency(self, save_fig=False):
         """
         Plot efficiency vs wavelength.
 
         Parameters
         ----------
-        efficiency_type: str
-            The type of efficiency to plot (Cherenkov 'C' or NSB 'N')
         save_fig: bool
             If True, the figure will be saved to a file.
 
@@ -449,9 +523,9 @@ class CameraEfficiency:
         fig
             The figure instance of pyplot
         """
-        self._logger.info(f"Plotting {efficiency_type} efficiency vs wavelength")
+        self._logger.info(f"Plotting {self.efficiency_type} efficiency vs wavelength")
 
-        _col_type = "C" if efficiency_type == "Cherenkov" else "N"
+        _col_type = "C" if self.efficiency_type in ("shower", "muon") else "N"
 
         column_titles = {
             "wl": "Wavelength [nm]",
@@ -469,21 +543,21 @@ class CameraEfficiency:
         for column_now, column_title in column_titles.items():
             table_to_plot.rename_column(column_now, column_title)
 
-        y_title = f"{efficiency_type} light efficiency"
-        if efficiency_type == "NSB":
+        y_title = f"{self.efficiency_type} light efficiency"
+        if self.efficiency_type == "nsb":
             y_title = r"Diff. ph. rate [$10^{9} \times $ph/(nm s m$^2$ sr)]"
         plot = visualize.plot_table(
             table_to_plot,
             y_title=y_title,
-            title=f"{self.telescope_model.name} response to {efficiency_type} light",
+            title=f"{self.telescope_model.name} response to {self.efficiency_type} light",
             no_markers=True,
         )
-        if efficiency_type == "NSB":
+        if self.efficiency_type == "nsb":
             plot.gca().set_yscale("log")
             ylim = plot.gca().get_ylim()
             plot.gca().set_ylim(1e-3, ylim[1])
         if save_fig:
-            self._save_plot(plot, efficiency_type.lower())
+            self._save_plot(plot, self.efficiency_type)
         return plot
 
     def _save_plot(self, fig, plot_title):
@@ -501,3 +575,47 @@ class CameraEfficiency:
             self.label + "_" + self.telescope_model.name + "_" + plot_title
         )
         visualize.save_figure(fig, plot_file, log_title=f"{plot_title} efficiency")
+
+    def dump_nsb_pixel_rate(self):
+        """Write NSB pixel rate parameter file."""
+        cfg = settings.config.args
+
+        writer.ModelDataWriter.dump_model_parameter(
+            parameter_name="nsb_pixel_rate",
+            value=self.get_nsb_pixel_rate(
+                reference_conditions=settings.config.args.get(
+                    "write_reference_nsb_rate_as_parameter", False
+                )
+            ),
+            instrument=cfg.get("telescope"),
+            parameter_version=cfg.get("parameter_version") or "0.0.0",
+            output_file=Path(f"nsb_pixel_rate-{cfg.get('parameter_version', '0.0.0')}.json"),
+            output_path=self.output_dir / cfg.get("telescope") / "nsb_pixel_rate",
+        )
+
+    def _get_x_max_for_efficiency_type(self):
+        """
+        Get X max value in g/cm2 depending on the efficiency type.
+
+        Returns
+        -------
+        float
+             max value in g/cm2
+        """
+        # typical value for shower X-max around 10 km (not relevant for NSB type)
+        x_max = 300.0
+        obs_level = self.site_model.get_parameter_value_with_unit("corsika_observation_level")
+        if self.efficiency_type == "muon":
+            atmo = AtmosphereProfile(
+                self.site_model.config_file_directory
+                / self.site_model.get_parameter_value("atmospheric_profile")
+            )
+            alt = obs_level.to(u.km) + 0.1 * u.km
+            x_max = atmo.interpolate(altitude=alt, column="thick")
+
+        self._logger.info(
+            f"Using X-max for {self.efficiency_type} efficiency: {x_max:.2f} g/cm2"
+            f" (at observation level: {obs_level:.2f})"
+        )
+
+        return x_max

simtools/camera/single_photon_electron_spectrum.py

@@ -2,7 +2,6 @@
 
 import logging
 import re
-import subprocess
 import tempfile
 from io import BytesIO
 from pathlib import Path
@@ -12,10 +11,12 @@ from astropy.table import Table
 from scipy.optimize import curve_fit
 
 import simtools.data_model.model_data_writer as writer
+from simtools import settings
 from simtools.constants import MODEL_PARAMETER_SCHEMA_URL, SCHEMA_PATH
 from simtools.data_model import validate_data
 from simtools.data_model.metadata_collector import MetadataCollector
 from simtools.io import io_handler
+from simtools.job_execution import job_manager
 
 
 class SinglePhotonElectronSpectrum:
@@ -96,7 +97,8 @@ class SinglePhotonElectronSpectrum:
         )
 
         writer.ModelDataWriter.dump(
-            args_dict=self.args_dict,
+            output_file=self.args_dict["output_file"],
+            output_file_format=self.args_dict.get("output_file_format"),
             metadata=self.metadata,
             product_data=table,
             validate_schema_file=None,
@@ -125,7 +127,7 @@ class SinglePhotonElectronSpectrum:
 
         Raises
         ------
-        subprocess.CalledProcessError
+        job_manager.JobExecutionError
             If the command execution fails.
         """
         tmp_input_file = self._get_input_data(
@@ -140,7 +142,7 @@ class SinglePhotonElectronSpectrum:
         )
 
         command = [
-            f"{self.args_dict['simtel_path']}/sim_telarray/bin/norm_spe",
+            f"{settings.config.sim_telarray_path}/bin/norm_spe",
             "-r",
             f"{self.args_dict['step_size']},{self.args_dict['max_amplitude']}",
         ]
@@ -152,10 +154,9 @@ class SinglePhotonElectronSpectrum:
 
         self._logger.info(f"Running norm_spe command: {' '.join(command)}")
         try:
-            result = subprocess.run(command, capture_output=True, text=True, check=True)
-        except subprocess.CalledProcessError as exc:
+            result = job_manager.submit(command)
+        except job_manager.JobExecutionError as exc:
             self._logger.error(f"Error running norm_spe: {exc}")
-            self._logger.error(f"stderr: {exc.stderr}")
             raise exc
         finally:
             for tmp_file in [tmp_input_file, tmp_ap_file]:

simtools/configuration/commandline_parser.py

@@ -8,6 +8,7 @@ from pathlib import Path
 import astropy.units as u
 
 import simtools.version
+from simtools import constants
 from simtools.utils import names
 
 
@@ -106,7 +107,7 @@ class CommandLineParser(argparse.ArgumentParser):
             required=False,
         )
         _job_group.add_argument(
-            "--simtel_path",
+            "--sim_telarray_path",
             help="path pointing to sim_telarray installation",
             type=Path,
             required=False,
@@ -160,6 +161,18 @@ class CommandLineParser(argparse.ArgumentParser):
         _job_group.add_argument(
             "--version", action="version", version=f"%(prog)s {simtools.version.__version__}"
         )
+        _job_group.add_argument(
+            "--build_info",
+            action=BuildInfoAction,
+            build_info=f"%(prog)s {simtools.version.__version__}",
+            help="show build information and exit",
+        )
+        _job_group.add_argument(
+            "--export_build_info",
+            help="export build information to file",
+            required=False,
+            type=str,
+        )
 
     def initialize_user_arguments(self):
         """Initialize user arguments."""
@@ -269,7 +282,7 @@ class CommandLineParser(argparse.ArgumentParser):
                 type=self.telescope,
             )
         if "layout" in model_options or "layout_file" in model_options:
-            _job_group = self._add_model_option_layout(
+            self._add_model_option_layout(
                 job_group=_job_group,
                 model_options=model_options,
                 # layout info is always required for layout related tasks with the exception
@@ -277,6 +290,13 @@ class CommandLineParser(argparse.ArgumentParser):
                 required="--list_available_layouts" not in self._option_string_actions,
             )
 
+        _job_group.add_argument(
+            "--ignore_missing_design_model",
+            help="Ignore missing design model definition of DB",
+            action="store_true",
+            required=False,
+        )
+
     def initialize_simulation_configuration_arguments(self, simulation_configuration):
         """
         Initialize default arguments for simulation configuration and simulation software.
@@ -438,21 +458,35 @@ class CommandLineParser(argparse.ArgumentParser):
     def _get_dictionary_with_sim_telarray_configuration():
         """Return dictionary with sim_telarray configuration parameters."""
         return {
-            "sim_telarray_instrument_seeds": {
-                "help": (
-                    "Random seed used for sim_telarray instrument setup. "
-                    "If '--sim_telarray_random_instrument_instances' is not set: "
-                    "use as sim_telarray seed ('random_seed' parameter). Otherwise: "
-                    "use as base seed to generate the random instrument instance seeds."
-                ),
-                "type": str,
+            "sim_telarray_instrument_seed": {
+                "help": "Random seed used for sim_telarray instrument setup.",
+                "type": CommandLineParser.bounded_int(1, constants.SIMTEL_MAX_SEED),
                 "required": False,
             },
             "sim_telarray_random_instrument_instances": {
                 "help": "Number of random instrument instances initialized in sim_telarray.",
-                "type": int,
+                "type": CommandLineParser.bounded_int(1, 1024),
+                "required": False,
+                "default": 1,
+            },
+            "sim_telarray_seed": {
+                "help": (
+                    "Random seed used for sim_telarray simulation. "
+                    "Single value: seed for event simulation. "
+                    "Two values: [instrument_seed, simulation_seed] (use for testing only)."
+                ),
+                "type": CommandLineParser.bounded_int(1, constants.SIMTEL_MAX_SEED),
+                "nargs": "+",
                 "required": False,
             },
+            # hidden argument to specify the sim_telarray seeds file name
+            # (defined it here for convenience)
+            "sim_telarray_seed_file": {
+                "help": argparse.SUPPRESS,
+                "type": str,
+                "required": False,
+                "default": "sim_telarray_instrument_seeds.txt",
+            },
         }
 
     def _initialize_simulation_configuration(
@@ -825,3 +859,40 @@ class CommandLineParser(argparse.ArgumentParser):
             raise ValueError("Input string does not contain an integer and a astropy quantity.")
 
         return (int(match.group(1)), u.Quantity(float(match.group(2)), match.group(3)))
+
+    @staticmethod
+    def bounded_int(min_value, max_value):
+        """Argument parser type to check that an integer is within a given interval."""
+
+        def bounded_int_type(value):
+            try:
+                int_value = int(value)
+            except ValueError as exc:
+                raise ValueError(f"expected an integer in [{min_value},{max_value}]") from exc
+
+            if min_value <= int_value <= max_value:
+                return int_value
+            raise ValueError(f"{int_value} not in [{min_value},{max_value}]")
+
+        return bounded_int_type
+
+
+class BuildInfoAction(argparse.Action):
+    """Custom argparse action to display build information."""
+
+    def __init__(self, option_strings, dest=argparse.SUPPRESS, default=argparse.SUPPRESS, **kwargs):
+        """Initialize BuildInfoAction."""
+        self.build_info = kwargs.pop("build_info", "Build information")
+        kwargs.pop("nargs", None)
+        super().__init__(option_strings, dest=dest, default=default, nargs=0, **kwargs)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        """Display build information and exit."""
+        # for efficiency reason, allow import here
+        from simtools import dependencies  # pylint: disable=C0415
+
+        build_options = dependencies.get_build_options()
+        print(f"{self.build_info}")
+        for key, value in build_options.items():
+            print(f"{key}: {value}")
+        parser.exit()