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

simtools/model/camera.py

@@ -1,6 +1,7 @@
 """Definition and modeling of camera."""
 
 import logging
+from pathlib import Path
 
 import astropy.units as u
 import numpy as np
@@ -20,9 +21,9 @@ class Camera:
 
     Parameters
     ----------
-    telescope_model_name: string
+    telescope_model_name: str
         As provided by the telescope model method TelescopeModel (e.g., LSTN-01)
-    camera_config_file: string
+    camera_config_file: str or Path
         The sim_telarray file name.
     focal_length: float
         The focal length of the camera in (preferably the effective focal length), assumed to be \
@@ -34,7 +35,9 @@ class Camera:
     SIPM_NEIGHBOR_RADIUS_FACTOR = 1.4
     SIPM_ROW_COLUMN_DIST_FACTOR = 0.2
 
-    def __init__(self, telescope_model_name, camera_config_file, focal_length):
+    def __init__(
+        self, telescope_model_name: str, camera_config_file: str | Path, focal_length: float
+    ):
         """
         Initialize Camera class, defining pixel layout.
 
@@ -58,13 +61,13 @@ class Camera:
         self._edge_pixel_indices = None
 
     @staticmethod
-    def read_pixel_list(camera_config_file):
+    def read_pixel_list(camera_config_file: str | Path) -> dict:
         """
         Read the pixel layout from the camera config file, assumed to be in a sim_telarray format.
 
         Parameters
         ----------
-        camera_config_file: string
+        camera_config_file: str or Path
             The sim_telarray file name.
 
         Returns
@@ -90,7 +93,7 @@ class Camera:
         return pixels
 
     @staticmethod
-    def initialize_pixel_dict():
+    def initialize_pixel_dict() -> dict:
         """
         Initialize the pixel dictionary with default values.
 
@@ -113,16 +116,16 @@ class Camera:
         }
 
     @staticmethod
-    def process_line(line, pixels):
+    def process_line(line: str, pixels: dict):
         """
-        Process a line from the camera config file and update the pixel dictionary.
+        Process a line from the camera config file and update the pixels dictionary.
 
         Parameters
         ----------
-        line: string
+        line: str
             A line from the camera config file.
         pixels: dict
-            The pixel dictionary to update.
+            The dictionary to update with pixel information.
         """
         pix_info = line.split()
 
@@ -150,9 +153,9 @@ class Camera:
                 pixels["pix_on"].append(True)
 
     @staticmethod
-    def validate_pixels(pixels, camera_config_file):
+    def validate_pixels(pixels: dict, camera_config_file: str | Path):
         """
-        Validate the pixel dictionary to ensure it has correct values.
+        Validate the pixel dictionary to ensure all required fields are present.
 
         Parameters
         ----------
@@ -174,7 +177,7 @@ class Camera:
                 f"Pixel shape in {camera_config_file} unrecognized (has to be 1, 2 or 3)"
             )
 
-    def _rotate_pixels(self, pixels):
+    def _rotate_pixels(self, pixels: dict) -> dict:
         """
         Rotate the pixels according to the rotation angle given in pixels['rotate_angle'].
 
@@ -184,7 +187,7 @@ class Camera:
 
         Parameters
         ----------
-        pixels: dictionary
+        pixels: dict
             The dictionary produced by the read_pixel_list method of this class
 
         Returns
@@ -219,9 +222,9 @@ class Camera:
 
         return pixels
 
-    def get_number_of_pixels(self):
+    def get_number_of_pixels(self) -> int:
         """
-        Get the number of pixels in the camera (all pixels, including those defined as "off".
+        Get the number of pixels in the camera (all pixels, including those defined as "off").
 
         Returns
         -------
@@ -230,7 +233,7 @@ class Camera:
         """
         return len(self.pixels["x"])
 
-    def get_pixel_diameter(self):
+    def get_pixel_diameter(self) -> float:
         """
         Get pixel diameter contained in _pixels.
 
@@ -241,7 +244,7 @@ class Camera:
         """
         return self.pixels["pixel_diameter"]
 
-    def get_pixel_active_solid_angle(self):
+    def get_pixel_active_solid_angle(self) -> float:
         """
         Get the active solid angle of a pixel in sr.
 
@@ -256,7 +259,7 @@ class Camera:
             pixel_area *= np.sqrt(3) / 2
         return pixel_area / (self.focal_length**2)
 
-    def get_pixel_shape(self):
+    def get_pixel_shape(self) -> int:
         """
         Get pixel shape code 1, 2 or 3.
 
@@ -270,7 +273,7 @@ class Camera:
         """
         return self.pixels["pixel_shape"]
 
-    def get_lightguide_efficiency_angle_file_name(self):
+    def get_lightguide_efficiency_angle_file_name(self) -> str:
         """
         Get the file name of the light guide efficiency as a function of incidence angle.
 
@@ -281,7 +284,7 @@ class Camera:
         """
         return self.pixels["lightguide_efficiency_angle_file"]
 
-    def get_lightguide_efficiency_wavelength_file_name(self):
+    def get_lightguide_efficiency_wavelength_file_name(self) -> str:
         """
         Get the file name of the light guide efficiency as a function of wavelength.
 
@@ -292,7 +295,7 @@ class Camera:
         """
         return self.pixels["lightguide_efficiency_wavelength_file"]
 
-    def get_camera_fill_factor(self):
+    def get_camera_fill_factor(self) -> float:
         """
         Calculate the fill factor of the camera, defined as (pixel_diameter/pixel_spacing)**2.
 
@@ -311,7 +314,7 @@ class Camera:
 
         return (self.pixels["pixel_diameter"] / self.pixels["pixel_spacing"]) ** 2
 
-    def calc_fov(self):
+    def calc_fov(self) -> tuple[float, float]:
         """
         Calculate the FOV of the camera in degrees, taking into account the focal length.
 
@@ -327,7 +330,6 @@ class Camera:
         The x,y pixel positions and focal length are assumed to have the same unit (usually cm)
         """
         self._logger.debug("Calculating the FoV")
-
         return self._calc_fov(
             self.pixels["x"],
             self.pixels["y"],
@@ -335,7 +337,13 @@ class Camera:
             self.focal_length,
         )
 
-    def _calc_fov(self, x_pixel, y_pixel, edge_pixel_indices, focal_length):
+    def _calc_fov(
+        self,
+        x_pixel: list[float],
+        y_pixel: list[float],
+        edge_pixel_indices: list[int],
+        focal_length: float,
+    ) -> tuple[float, float]:
         """
         Calculate the FOV of the camera in degrees, taking into account the focal length.
 
@@ -374,7 +382,7 @@ class Camera:
         return fov, average_edge_distance
 
     @staticmethod
-    def _find_neighbors(x_pos, y_pos, radius):
+    def _find_neighbors(x_pos: np.ndarray, y_pos: np.ndarray, radius: float) -> list[list[int]]:
         """
         Use a KD-Tree to quickly find nearest neighbors.
 
@@ -392,20 +400,16 @@ class Camera:
 
         Returns
         -------
-        neighbors: numpy.array_like
-            Array of neighbor indices in a list for each e.g., pixel.
+        list of lists
+            Array of neighbor indices in a list for each pixel
         """
-        points = np.array([x_pos, y_pos]).T
-        indices = np.arange(len(x_pos))
-        kdtree = KDTree(points)
-        neighbors = [kdtree.query_ball_point(p, r=radius) for p in points]
+        tree = KDTree(np.column_stack([x_pos, y_pos]))
+        neighbors = tree.query_ball_tree(tree, radius)
+        return [list(np.setdiff1d(neigh, [i])) for i, neigh in enumerate(neighbors)]
 
-        for neighbor_now, index_now in zip(neighbors, indices):
-            neighbor_now.remove(index_now)  # get rid of the pixel or mirror itself
-
-        return neighbors
-
-    def _find_adjacent_neighbor_pixels(self, x_pos, y_pos, radius, row_column_dist):
+    def _find_adjacent_neighbor_pixels(
+        self, x_pos: np.ndarray, y_pos: np.ndarray, radius: float, row_column_dist: float
+    ) -> list[list[int]]:
         """
         Find adjacent neighbor pixels in cameras with square pixels.
 
@@ -413,13 +417,13 @@ class Camera:
 
         Parameters
         ----------
-        x_pos : numpy.array_like
+        x_pos: np.ndarray
             x position of each pixel
-        y_pos : numpy.array_like
+        y_pos: np.ndarray
             y position of each pixel
-        radius : float
+        radius: float
             Radius within which to find neighbors
-        row_column_dist : float
+        row_column_dist: float
             Distance to consider for row/column adjacency.
             Should be around 20% of the pixel diameter.
 
@@ -441,23 +445,31 @@ class Camera:
 
         return neighbors
 
-    def _add_additional_neighbors(self, i_pix, nn, x_pos, y_pos, radius, row_column_dist):
+    def _add_additional_neighbors(
+        self,
+        i_pix: int,
+        nn: list[int],
+        x_pos: np.ndarray,
+        y_pos: np.ndarray,
+        radius: float,
+        row_column_dist: float,
+    ):
         """
         Add neighbors for a given pixel if they are not already neighbors and are adjacent.
 
         Parameters
         ----------
-        i_pix : int
+        i_pix: int
             Index of the pixel to find neighbors for
-        nn : list
+        nn: list
             Current list of neighbors for the pixel
-        x_pos : numpy.array_like
+        x_pos: np.ndarray
             x position of each pixel
-        y_pos : numpy.array_like
+        y_pos: np.ndarray
             y position of each pixel
-        radius : float
+        radius: float
             Radius within which to find neighbors
-        row_column_dist : float
+        row_column_dist: float
             Distance to consider for row/column adjacency
         """
         for j_pix, _ in enumerate(x_pos):
@@ -477,20 +489,20 @@ class Camera:
                 ) and dist < 1.2 * radius:
                     nn.append(j_pix)
 
-    def _calc_neighbor_pixels(self, pixels):
+    def _calc_neighbor_pixels(self, pixels: dict) -> list[list[int]]:
         """
         Find adjacent neighbor pixels in cameras with hexagonal or square pixels.
 
-        Only directly  adjacent neighbors are searched for, no diagonals.
+        Only directly adjacent neighbors are searched for, no diagonals.
 
         Parameters
         ----------
-        pixels: dictionary
+        pixels: dict
             The dictionary produced by the read_pixel_list method of this class
 
         Returns
         -------
-        neighbors: numpy.array_like
+        neighbors: list of lists
             Array of neighbor indices in a list for each pixel
         """
         self._logger.debug("Searching for neighbor pixels")
@@ -515,7 +527,7 @@ class Camera:
 
         return self._neighbors
 
-    def get_neighbor_pixels(self, pixels=None):
+    def get_neighbor_pixels(self, pixels: dict | None = None) -> list[list[int]]:
         """
         Get a list of neighbor pixels by calling calc_neighbor_pixels() when necessary.
 
@@ -529,7 +541,7 @@ class Camera:
 
         Returns
         -------
-        neighbors: numpy.array_like
+        neighbors: list of lists
             Array of neighbor indices in a list for each pixel.
         """
         if self._neighbors is None:
@@ -539,20 +551,20 @@ class Camera:
 
         return self._neighbors
 
-    def _calc_edge_pixels(self, pixels, neighbors):
+    def _calc_edge_pixels(self, pixels: dict, neighbors: list[list[int]]) -> list[int]:
         """
         Find the edge pixels of the camera.
 
         Parameters
         ----------
-        pixels: dictionary
+        pixels: dict
             The dictionary produced by the read_pixel_list method of this class.
-        neighbors: numpy.array_like
+        neighbors: list of lists
             Array of neighbor indices in a list for each pixel.
 
         Returns
         -------
-        edge_pixel_indices: numpy.array_like
+        edge_pixel_indices: list
             Array of edge pixel indices.
         """
         self._logger.debug("Searching for edge pixels")
@@ -574,7 +586,9 @@ class Camera:
 
         return edge_pixel_indices
 
-    def get_edge_pixels(self, pixels=None, neighbors=None):
+    def get_edge_pixels(
+        self, pixels: dict | None = None, neighbors: list[list[int]] | None = None
+    ) -> list[int]:
         """
         Get the indices of the edge pixels of the camera.
 
@@ -582,12 +596,12 @@ class Camera:
         ----------
         pixels: dict
             The dictionary produced by the read_pixel_list method of this class.
-        neighbors: numpy.array_like
+        neighbors: list of lists
             Array of neighbor indices in a list for each pixel.
 
         Returns
         -------
-        edge_pixel_indices: numpy.array_like
+        edge_pixel_indices: list
             Array of edge pixel indices.
         """
         if self._edge_pixel_indices is None:

simtools/model/mirrors.py

@@ -1,6 +1,7 @@
 """Definition and modeling of mirror panels."""
 
 import logging
+from pathlib import Path
 
 import astropy.io.ascii
 import astropy.units as u
@@ -20,13 +21,13 @@ class Mirrors:
 
     Parameters
     ----------
-    mirror_list_file: str
-        mirror list in sim_telarray or ecsv format (with panel focal length only).
-    parameters: dict
+    mirror_list_file: Union[str, Path]
+        Mirror list in sim_telarray or ecsv format (with panel focal length only).
+    parameters: dict, optional
         Dictionary of parameters from the database.
     """
 
-    def __init__(self, mirror_list_file, parameters=None):
+    def __init__(self, mirror_list_file: str | Path, parameters: dict | None = None):
         """Initialize Mirrors."""
         self._logger = logging.getLogger(__name__)
         self._logger.debug("Mirrors Init")
@@ -180,7 +181,7 @@ class Mirrors:
         self._logger.debug(f"Mirror diameter = {self.mirror_diameter}")
         self._logger.debug(f"Number of Mirrors = {self.number_of_mirrors}")
 
-    def get_single_mirror_parameters(self, number):
+    def get_single_mirror_parameters(self, number: int) -> tuple:
         """
         Get parameters for a single mirror given by number.
 
@@ -191,7 +192,8 @@ class Mirrors:
 
         Returns
         -------
-        (pos_x, pos_y, mirror_diameter, focal_length, shape_type): tuple of float
+        tuple
+            (pos_x, pos_y, mirror_diameter, focal_length, shape_type): tuple of float
             X, Y positions, mirror_diameter, focal length and shape_type.
         """
         mask = self.mirror_table["mirror_panel_id"] == number

simtools/model/model_parameter.py

@@ -456,7 +456,7 @@ class ModelParameter:
         Change values of multiple existing parameters in the model from a file.
 
         This function does not modify the DB, it affects only the current instance.
-        Experimental feature: insufficient validation of parameters.
+        This feature is intended for developers and lacks validation.
 
         Parameters
         ----------
@@ -464,7 +464,7 @@ class ModelParameter:
             File containing the parameters to be changed.
         """
         self._logger.warning(
-            "Changing multiple parameters from file is an experimental feature."
+            "Changing multiple parameters from file is a feature for developers."
             "Insufficient validation of parameters."
         )
         self._logger.debug(f"Changing parameters from file {file_name}")

simtools/model/model_utils.py

@@ -11,7 +11,7 @@ __all__ = [
 ]
 
 
-def compute_telescope_transmission(pars, off_axis):
+def compute_telescope_transmission(pars: list[float], off_axis: float) -> float:
     """
     Compute telescope transmission (0 < T < 1) for a given off-axis angle.
 
@@ -20,7 +20,7 @@ def compute_telescope_transmission(pars, off_axis):
     Parameters
     ----------
     pars: list of float
-        Parameters of the telescope transmission. Len(pars) should be 4.
+        Parameters of the telescope transmission. Len(pars) should be 5 or 6.
     off_axis: float
         Off-axis angle in deg.
 
@@ -37,19 +37,19 @@ def compute_telescope_transmission(pars, off_axis):
     return pars[0] / (1.0 + pars[2] * t ** pars[4])
 
 
-def is_two_mirror_telescope(telescope_model_name):
+def is_two_mirror_telescope(telescope_model_name: str) -> bool:
     """
-    Check if the telescope is a two mirror design.
+    Determine if the telescope model is a two-mirror telescope.
 
     Parameters
     ----------
     telescope_model_name: str
-        Telescope model name (ex. LSTN-01).
+        Name of the telescope model.
 
     Returns
     -------
     bool
-        True if the telescope is a two mirror one.
+        True if it is a two-mirror telescope.
     """
     tel_type = names.get_array_element_type_from_name(telescope_model_name)
     if "SST" in tel_type or "SCT" in tel_type:

simtools/model/site_model.py

@@ -21,7 +21,7 @@ class SiteModel(ModelParameter):
         MongoDB configuration.
     model_version: str
         Model version.
-    label: str
+    label: str, optional
         Instance label. Important for output file naming.
     """
 

simtools/model/telescope_model.py

@@ -1,6 +1,7 @@
 """MC model of a telescope."""
 
 import logging
+from pathlib import Path
 
 import astropy.io.ascii
 import numpy as np
@@ -31,23 +32,20 @@ class TelescopeModel(ModelParameter):
         MongoDB configuration.
     model_version: str
         Model version.
-    label: str
+    label: str, optional
         Instance label. Important for output file naming.
     """
 
     def __init__(
         self,
-        site,
-        telescope_name,
-        mongo_db_config,
-        model_version,
-        label=None,
+        site: str,
+        telescope_name: str,
+        mongo_db_config: dict,
+        model_version: str,
+        label: str | None = None,
     ):
         """Initialize TelescopeModel."""
-        self._logger = logging.getLogger(__name__)
-        self._logger.debug("Init TelescopeModel %s %s", site, telescope_name)
-        ModelParameter.__init__(
-            self,
+        super().__init__(
             site=site,
             array_element_name=telescope_name,
             mongo_db_config=mongo_db_config,
@@ -56,6 +54,9 @@ class TelescopeModel(ModelParameter):
             label=label,
         )
 
+        self._logger = logging.getLogger(__name__)
+        self._logger.debug("Init TelescopeModel %s %s", site, telescope_name)
+
         self._single_mirror_list_file_paths = None
         self._mirrors = None
         self._camera = None
@@ -74,7 +75,7 @@ class TelescopeModel(ModelParameter):
             self._load_camera()
         return self._camera
 
-    def export_single_mirror_list_file(self, mirror_number, set_focal_length_to_zero):
+    def export_single_mirror_list_file(self, mirror_number: int, set_focal_length_to_zero: bool):
         """
         Export a mirror list file with a single mirror in it.
 
@@ -107,7 +108,9 @@ class TelescopeModel(ModelParameter):
             set_focal_length_to_zero,
         )
 
-    def get_single_mirror_list_file(self, mirror_number, set_focal_length_to_zero=False):
+    def get_single_mirror_list_file(
+        self, mirror_number: int, set_focal_length_to_zero: bool = False
+    ):
         """
         Get the path to the single mirror list file.
 
@@ -143,7 +146,9 @@ class TelescopeModel(ModelParameter):
 
         self._mirrors = Mirrors(mirror_list_file, parameters=self._parameters)
 
-    def get_telescope_effective_focal_length(self, unit="m", return_focal_length_if_zero=False):
+    def get_telescope_effective_focal_length(
+        self, unit: str = "m", return_focal_length_if_zero: bool = False
+    ) -> float:
         """
         Return effective focal length.
 
@@ -160,7 +165,6 @@ class TelescopeModel(ModelParameter):
         -------
         float:
             Effective focal length.
-
         """
         try:
             eff_focal_length = self.get_parameter_value_with_unit("effective_focal_length")[0]
@@ -200,7 +204,7 @@ class TelescopeModel(ModelParameter):
             focal_length=focal_length,
         )
 
-    def is_file_2d(self, par):
+    def is_file_2d(self, par: str) -> bool:
         """
         Check if the file referenced by par is a 2D table.
 
@@ -212,7 +216,7 @@ class TelescopeModel(ModelParameter):
         Returns
         -------
         bool:
-            True if the file is a 2D map type, False otherwise.
+            True if the file is a 2D map type.
         """
         try:
             file_name = self.get_parameter_value(par)
@@ -224,7 +228,7 @@ class TelescopeModel(ModelParameter):
         with open(file, encoding="utf-8") as f:
             return "@RPOL@" in f.read()
 
-    def read_two_dim_wavelength_angle(self, file_name):
+    def read_two_dim_wavelength_angle(self, file_name: str | Path) -> dict:
         """
         Read a two dimensional distribution of wavelength and angle (z-axis can be anything).
 
@@ -259,7 +263,7 @@ class TelescopeModel(ModelParameter):
             "z": np.array(_data[:, 1:]).T,
         }
 
-    def get_on_axis_eff_optical_area(self):
+    def get_on_axis_eff_optical_area(self) -> float:
         """Return the on-axis effective optical area (derived previously for this telescope)."""
         ray_tracing_data = astropy.io.ascii.read(
             self.config_file_directory.joinpath(self.get_parameter_value("optics_properties"))
@@ -272,7 +276,7 @@ class TelescopeModel(ModelParameter):
             raise ValueError
         return ray_tracing_data["eff_area"][0]
 
-    def read_incidence_angle_distribution(self, incidence_angle_dist_file):
+    def read_incidence_angle_distribution(self, incidence_angle_dist_file: str) -> Table:
         """
         Read the incidence angle distribution from a file.
 
@@ -293,7 +297,7 @@ class TelescopeModel(ModelParameter):
         return astropy.io.ascii.read(self.config_file_directory.joinpath(incidence_angle_dist_file))
 
     @staticmethod
-    def calc_average_curve(curves, incidence_angle_dist):
+    def calc_average_curve(curves: dict, incidence_angle_dist: Table) -> Table:
         """
         Calculate an average curve from a set of curves.
 
@@ -328,7 +332,7 @@ class TelescopeModel(ModelParameter):
             names=("Wavelength", "z"),
         )
 
-    def export_table_to_model_directory(self, file_name, table):
+    def export_table_to_model_directory(self, file_name: str, table: Table) -> str:
         """
         Write out a file with the provided table to the model directory.
 
@@ -348,7 +352,7 @@ class TelescopeModel(ModelParameter):
         table.write(file_to_write_to, format="ascii.commented_header", overwrite=True)
         return file_to_write_to.absolute()
 
-    def position(self, coordinate_system="ground"):
+    def position(self, coordinate_system: str = "ground") -> list:
         """
         Get coordinates in the given system.
 

simtools/schemas/model_parameters/adjust_gain.schema.yml

@@ -3,7 +3,7 @@
 title: Schema for adjust_gain model parameter
 version: 0.1.0
 meta_schema: simpipe-schema
-meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
+meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/src/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
 meta_schema_version: 0.1.0
 name: adjust_gain
 description: |-

simtools/schemas/model_parameters/altitude.schema.yml

@@ -3,7 +3,7 @@
 title: Schema for altitude model parameter
 version: 0.1.0
 meta_schema: simpipe-schema
-meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
+meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/src/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
 meta_schema_version: 0.1.0
 name: altitude
 description: |-

simtools/schemas/model_parameters/array_coordinates.schema.yml

@@ -3,7 +3,7 @@
 title: Schema for array_coordinates model parameter
 version: 0.1.0
 meta_schema: simpipe-schema
-meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
+meta_schema_url: https://raw.githubusercontent.com/gammasim/simtools/main/src/simtools/schemas/model_parameter_and_data_schema.metaschema.yml
 meta_schema_version: 0.1.0
 developer_note: To be replaced by a data table
 name: array_coordinates