gammasimtools 0.6.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

simtools/corsika/corsika_histograms_visualize.py

@@ -1,3 +1,5 @@
+"""Visualize Cherenkov photon distributions from CORSIKA."""
+
 import logging
 from pathlib import Path
 
@@ -12,10 +14,9 @@ _logger = logging.getLogger(__name__)
 
 def _kernel_plot_2d_photons(histograms_instance, property_name, log_z=False):
     """
-    The next functions below are used by the the CorsikaHistograms class to plot all sort of
-    information from the Cherenkov photons saved.
+    Provide helper functions for plotting Cherenkov photon distributions saved in CorsikaHistograms.
 
-    Create the figure of a 2D plot. The parameter `name` indicate which plot.
+    Create the figure of a 2D plot. The parameter name indicate which plot.
     Choices are "counts", "density", "direction", "time_altitude", and "num_photons_per_telescope".
 
     Parameters
@@ -36,7 +37,7 @@ def _kernel_plot_2d_photons(histograms_instance, property_name, log_z=False):
     Raises
     ------
     ValueError
-        if `property` is not allowed.
+        if property is not allowed.
     """
     if property_name not in histograms_instance.dict_2d_distributions:
         msg = (
@@ -44,12 +45,12 @@ def _kernel_plot_2d_photons(histograms_instance, property_name, log_z=False):
             f"{histograms_instance.dict_2d_distributions}"
         )
         _logger.error(msg)
-        raise ValueError
-    function = getattr(
+        raise ValueError(msg)
+    _function = getattr(
         histograms_instance,
         histograms_instance.dict_2d_distributions[property_name]["function"],
     )
-    hist_values, x_bin_edges, y_bin_edges = function()
+    hist_values, x_bin_edges, y_bin_edges = _function()
 
     all_figs = []
     for i_hist, _ in enumerate(x_bin_edges):
@@ -215,7 +216,7 @@ def plot_2d_num_photons_per_telescope(histograms_instance, log_z=True):
 
 def _kernel_plot_1d_photons(histograms_instance, property_name, log_y=True):
     """
-    Create the figure of a 1D plot. The parameter `property` indicate which plot.
+    Create the figure of a 1D plot. The parameter property indicate which plot.
 
     Parameters
     ----------
@@ -236,7 +237,7 @@ def _kernel_plot_1d_photons(histograms_instance, property_name, log_y=True):
     Raises
     ------
     ValueError
-        if `property` is not allowed.
+        if property is not allowed.
     """
     if property_name not in histograms_instance.dict_1d_distributions:
         msg = (
@@ -244,13 +245,13 @@ def _kernel_plot_1d_photons(histograms_instance, property_name, log_y=True):
             f"{histograms_instance.dict_1d_distributions}"
         )
         _logger.error(msg)
-        raise ValueError
+        raise ValueError(msg)
 
-    function = getattr(
+    _function = getattr(
         histograms_instance,
         histograms_instance.dict_1d_distributions[property_name]["function"],
     )
-    hist_values, bin_edges = function()
+    hist_values, bin_edges = _function()
     all_figs = []
     for i_hist, _ in enumerate(bin_edges):
         fig, ax = plt.subplots()
@@ -299,7 +300,7 @@ def _kernel_plot_1d_photons(histograms_instance, property_name, log_y=True):
 
 def plot_wavelength_distr(histograms_instance, log_y=True):
     """
-    Plots the 1D distribution of the photon wavelengths
+    Plot the 1D distribution of the photon wavelengths.
 
     Parameters
     ----------
@@ -318,7 +319,7 @@ def plot_wavelength_distr(histograms_instance, log_y=True):
 
 def plot_counts_distr(histograms_instance, log_y=True):
     """
-    Plots the 1D distribution, i.e. the radial distribution, of the photons on the ground.
+    Plot the 1D distribution, i.e. the radial distribution, of the photons on the ground.
 
     Parameters
     ----------
@@ -337,7 +338,7 @@ def plot_counts_distr(histograms_instance, log_y=True):
 
 def plot_density_distr(histograms_instance, log_y=True):
     """
-    Plots the photon density distribution on the ground.
+    Plot the photon density distribution on the ground.
 
     Parameters
     ----------
@@ -356,7 +357,7 @@ def plot_density_distr(histograms_instance, log_y=True):
 
 def plot_time_distr(histograms_instance, log_y=True):
     """
-    Plots the distribution times in which the photons were generated in ns.
+    Plot the distribution times in which the photons were generated in ns.
 
     Parameters
     ----------
@@ -375,7 +376,7 @@ def plot_time_distr(histograms_instance, log_y=True):
 
 def plot_altitude_distr(histograms_instance, log_y=True):
     """
-    Plots the distribution of altitude in which the photons were generated in km.
+    Plot the distribution of altitude in which the photons were generated in km.
 
     Parameters
     ----------
@@ -394,7 +395,7 @@ def plot_altitude_distr(histograms_instance, log_y=True):
 
 def plot_photon_per_event_distr(histograms_instance, log_y=True):
     """
-    Plots the distribution of the number of Cherenkov photons per event.
+    Plot the distribution of the number of Cherenkov photons per event.
 
     Parameters
     ----------
@@ -409,13 +410,12 @@ def plot_photon_per_event_distr(histograms_instance, log_y=True):
         List of figures for the given telescopes.
 
     """
-
     return _kernel_plot_1d_photons(histograms_instance, "num_photons_per_event", log_y=log_y)
 
 
 def plot_photon_per_telescope_distr(histograms_instance, log_y=True):
     """
-    Plots the distribution of the number of Cherenkov photons per telescope.
+    Plot the distribution of the number of Cherenkov photons per telescope.
 
     Parameters
     ----------
@@ -430,7 +430,6 @@ def plot_photon_per_telescope_distr(histograms_instance, log_y=True):
         List of figures for the given telescopes.
 
     """
-
     return _kernel_plot_1d_photons(histograms_instance, "num_photons_per_telescope", log_y=log_y)
 
 
@@ -438,7 +437,7 @@ def plot_1d_event_header_distribution(
     histograms_instance, event_header_element, log_y=True, bins=50, hist_range=None
 ):
     """
-    Plots the distribution of the quantity given by .
+    Plot the distribution of the quantity given by .
 
     Parameters
     ----------
@@ -496,7 +495,7 @@ def plot_2d_event_header_distribution(
     hist_range=None,
 ):
     """
-    Plots the distribution of the quantity given by .
+    Plot the distribution of the quantity given by CorsikaHistograms.
 
     Parameters
     ----------
@@ -563,7 +562,7 @@ def save_figs_to_pdf(figs, pdf_file_name):
     Parameters
     ----------
     figs: list or numpy.array
-        List with the figures output by `corsika_output_visualize.py`.
+        List with the figures output by corsika_output_visualize.py.
     pdf_file_name: str or Path
         Name of the pdf file.
     """

simtools/corsika/primary_particle.py

@@ -0,0 +1,159 @@
+"""Primary particle definition."""
+
+import logging
+
+from particle import Corsika7ID, InvalidParticle, Particle
+
+
+class PrimaryParticle:
+    """
+    Primary particle definition using CORSIKA7 or PDG ID.
+
+    Uses a dictionary to map particle common names to CORSIKA7 IDs.
+    Particles not found in the dictionary are searched in the PDG particle database.
+
+    Parameters
+    ----------
+    particle_id_type : str
+        Type of the primary particle ID ('corsika7_id', 'common_name', or 'pdg_id').
+    particle_id : int or str
+        The actual ID of the primary particle.
+    """
+
+    def __init__(self, particle_id_type=None, particle_id=None):
+        self._logger = logging.getLogger(__name__)
+
+        self._corsika7_id = None
+        self._name = None
+        self._pdg_id = None
+        self._pdg_name = None
+
+        if bool(particle_id_type) != bool(particle_id):
+            raise ValueError("Both 'particle_id_type' and 'particle_id' must be provided together.")
+
+        valid_id_types = {"corsika7_id", "common_name", "pdg_id"}
+        if particle_id_type and particle_id_type not in valid_id_types:
+            raise ValueError(f"Particle ID type must be one of {valid_id_types}")
+
+        if particle_id_type == "corsika7_id":
+            self.corsika7_id = particle_id
+        elif particle_id_type == "common_name":
+            self.name = particle_id
+        elif particle_id_type == "pdg_id":
+            self.pdg_id = particle_id
+
+    def __str__(self):
+        """Return a string representation of the primary particle."""
+        return f"{self.name} ({self.corsika7_id}, {self.pdg_id}, {self.pdg_name})"
+
+    @property
+    def corsika7_id(self):
+        """CORSIKA7 ID of the primary particle."""
+        return self._corsika7_id
+
+    @corsika7_id.setter
+    def corsika7_id(self, value):
+        """Set CORSIKA7 ID of the primary particle."""
+        for name, ids in self.particle_names().items():
+            if value == ids["corsika7_id"]:
+                self._corsika7_id = int(value)
+                self._name = name
+                self._pdg_id = ids["pdg_id"]
+                self._pdg_name = ids["pdg_name"]
+                return
+        # no particle found - check PDG
+        try:
+            self._pdg_id = Corsika7ID(value).to_pdgid().numerator
+            self._pdg_name = Particle.findall(pdgid=self._pdg_id)[0].name
+            self._name = Corsika7ID(value).name()
+        except (IndexError, InvalidParticle) as exc:
+            raise ValueError(f"Invalid CORSIKA7 ID: {value}") from exc
+        self._corsika7_id = int(value)
+
+    @property
+    def name(self):
+        """Common name of the primary particle."""
+        return self._name
+
+    @name.setter
+    def name(self, value):
+        """Set common name of the primary particle."""
+        particles = self.particle_names()
+        if value.lower() in particles:
+            self._name = value.lower()
+            self._corsika7_id = particles[self._name]["corsika7_id"]
+            self._pdg_id = particles[self._name]["pdg_id"]
+            self._pdg_name = particles[self._name]["pdg_name"]
+            return
+
+        pdg_list = Particle.findall(lambda p: value in p.name)
+        if len(pdg_list) == 1:
+            self._pdg_id = pdg_list[0].pdgid.numerator
+            self._pdg_name = pdg_list[0].name
+            self._corsika7_id = Corsika7ID.from_pdgid(self._pdg_id).numerator
+            self._name = Corsika7ID.from_pdgid(self._pdg_id).name()
+            return
+        if len(pdg_list) > 1:
+            raise ValueError(f"Found more than one particle with name {value}: {pdg_list}")
+
+        raise ValueError(f"Invalid particle name: {value}")
+
+    @property
+    def pdg_id(self):
+        """PDG ID of the primary particle."""
+        return self._pdg_id
+
+    @pdg_id.setter
+    def pdg_id(self, value):
+        """Set PDG ID of the primary particle."""
+        # check if particle is in the default particle dictionary
+        for name, ids in self.particle_names().items():
+            if value == ids["pdg_id"]:
+                self._corsika7_id = ids["corsika7_id"]
+                self._name = name
+                self._pdg_id = value
+                self._pdg_name = ids["pdg_name"]
+                return
+        # no particle found - check PDG
+        try:
+            self._pdg_id = Particle.findall(pdgid=value)[0].pdgid.numerator
+            self._pdg_name = Particle.findall(pdgid=value)[0].name
+        except IndexError as exc:
+            raise ValueError(f"Invalid DPG ID: {value}") from exc
+        self._corsika7_id = Corsika7ID.from_pdgid(self._pdg_id).numerator
+        self._name = Corsika7ID.from_pdgid(self._pdg_id).name()
+
+    @property
+    def pdg_name(self):
+        """PDG name of the primary particle."""
+        return self._pdg_name
+
+    @staticmethod
+    def particle_names():
+        """
+        Primary particles including common names, CORSIKA7 IDs, and PDG IDs.
+
+        Returns
+        -------
+        dict
+            Dictionary of particle names, CORSIKA7 IDs, and PDG IDs.
+        """
+        particles = {
+            "gamma": {"corsika7_id": 1},
+            "electron": {"corsika7_id": 3},
+            "positron": {"corsika7_id": 2},
+            "muon+": {"corsika7_id": 5},
+            "muon-": {"corsika7_id": 6},
+            "proton": {"corsika7_id": 14},
+            "neutron": {"corsika7_id": 13},
+            "helium": {"corsika7_id": 402},
+            "carbon": {"corsika7_id": 601},
+            "nitrogen": {"corsika7_id": 1407},
+            "silicon": {"corsika7_id": 2814},
+            "iron": {"corsika7_id": 5626},
+        }
+        for _, ids in particles.items():
+            ids["pdg_id"] = Corsika7ID(ids["corsika7_id"]).to_pdgid().numerator
+            ids["pdg_name"] = Particle.findall(pdgid=ids["pdg_id"])[0].name
+
+        return particles

simtools/data_model/data_reader.py

@@ -1,3 +1,5 @@
+"""Helper module for reading of standardized simtools data products."""
+
 import logging
 
 import astropy.units as u
@@ -5,7 +7,7 @@ from astropy.io.registry.base import IORegistryError
 from astropy.table import QTable
 
 import simtools.utils.general as gen
-from simtools.data_model import metadata_model, validate_data
+from simtools.data_model import validate_data
 from simtools.data_model.metadata_collector import MetadataCollector
 
 __all__ = ["read_table_from_file", "read_value_from_file"]
@@ -16,12 +18,13 @@ _logger = logging.getLogger(__name__)
 def read_table_from_file(file_name, schema_file=None, validate=False, metadata_file=None):
     """
     Read astropy table from file and validate against schema.
+
     Metadata is read from metadata file or from the metadata section of the data file.
     Schema for validation can be given as argument, or is determined
     from the metadata associated to the file.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     file_name: str or Path
         Name of file to be read.
     schema_file: str or Path
@@ -31,8 +34,8 @@ def read_table_from_file(file_name, schema_file=None, validate=False, metadata_f
     metadata_file: str or Path
         Name of metadata file to be read.
 
-    Returns:
-    --------
+    Returns
+    -------
     astropy Table
         Table read from file.
 
@@ -42,7 +45,6 @@ def read_table_from_file(file_name, schema_file=None, validate=False, metadata_f
         If file does not exist.
 
     """
-
     try:
         data_table = QTable.read(file_name)
     except (FileNotFoundError, IORegistryError) as exc:
@@ -72,15 +74,17 @@ def read_table_from_file(file_name, schema_file=None, validate=False, metadata_f
 
 def read_value_from_file(file_name, schema_file=None, validate=False):
     """
-    Read value from file and validate against schema. Expect data to follow the convention for
+    Read value from file and validate against schema.
+
+    Expect data to follow the convention for
     how simulation model parameters are stored in the simulation model database: to be a single
     value stored in the 'value' field (with possible units in the 'units' field).
     Metadata is read from metadata file or from the metadata section of the data file.
     Schema for validation can be given as argument, or is determined
     from the metadata associated to the file.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     file_name: str or Path
         Name of file to be read.
     schema_file: str or Path
@@ -88,8 +92,8 @@ def read_value_from_file(file_name, schema_file=None, validate=False):
     validate: bool
         Validate data against schema (if true).
 
-    Returns:
-    --------
+    Returns
+    -------
     astro quantity or str
         Value read from file. If units are given, return an astropy quantity, otherwise a string.
         Return None if no value is found in the file.
@@ -100,9 +104,8 @@ def read_value_from_file(file_name, schema_file=None, validate=False):
         If file does not exist.
 
     """
-
     try:
-        data = gen.collect_data_from_file_or_dict(file_name=file_name, in_dict=None)
+        data = gen.collect_data_from_file(file_name=file_name)
     except FileNotFoundError as exc:
         _logger.error("Error reading data from %s", file_name)
         raise exc
@@ -117,13 +120,15 @@ def read_value_from_file(file_name, schema_file=None, validate=False):
             schema_file = _collector.get_data_model_schema_file_name()
             _logger.debug(f"Using schema from meta_data_url: {schema_file}")
 
-        metadata_model.validate_schema(data, schema_file)
+        _validator = validate_data.DataValidator(
+            schema_file=schema_file,
+            data_dict=data,
+        )
+        data = _validator.validate_and_transform()
         _logger.debug("Successful validation of yaml/json file")
 
-    if "Value" not in data or data["Value"] is None:
+    _value = data.get("value")
+    if _value is None:
         return None
-
-    if "units" in data and len(data["units"]) > 0:
-        return data["Value"] * u.Unit(data["units"])
-
-    return data["Value"]
+    _unit = data.get("unit")
+    return _value if _unit is None else _value * u.Unit(_unit)

simtools/data_model/format_checkers.py

@@ -0,0 +1,52 @@
+"""Custom format checkers for jsonschema validation."""
+
+import re
+
+import astropy.units as u
+import jsonschema
+
+from simtools.utils import names
+
+format_checker = jsonschema.FormatChecker()
+
+
+@format_checker.checks("astropy_unit")
+def check_astropy_unit(unit_string):
+    """Validate astropy units (including dimensionless) for jsonschema."""
+    try:
+        u.Unit(unit_string)
+    except (ValueError, TypeError) as exc:
+        if unit_string != "dimensionless":
+            raise ValueError(f"'{unit_string}' is not a valid Unit") from exc
+    return True
+
+
+@format_checker.checks("astropy_unit_of_time")
+def check_astropy_unit_of_time(unit_string):
+    """Validate astropy units that this is an astropy unit of time."""
+    u.Unit(unit_string).to("s")
+    return True
+
+
+@format_checker.checks("astropy_unit_of_length)")
+def check_astropy_unit_of_length(unit_string):
+    """Validate astropy units that this is an astropy unit of length."""
+    u.Unit(unit_string).to("m")
+    return True
+
+
+@format_checker.checks("array_element")
+def check_array_element(element):
+    """Validate array elements for jsonschema."""
+    names.validate_array_element_name(element)
+    return True
+
+
+@format_checker.checks("array_triggers_name")
+def check_array_triggers_name(name):
+    """Validate array trigger names for jsonschema."""
+    pattern = r"(.*)(?=_single_telescope|_array)"
+    if not re.match(pattern, name):
+        raise ValueError(f"Array trigger name '{name}' does not match pattern '{pattern}'")
+    names.validate_array_element_type(re.match(pattern, name).group(1))
+    return True