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

simtools/model/array_model.py

@@ -1,360 +1,253 @@
+"""Definition of the ArrayModel class."""
+
 import logging
-from copy import copy
+from pathlib import Path
+
+import astropy.units as u
+from astropy.table import QTable
 
-from simtools import db_handler
+from simtools.data_model import data_reader
+from simtools.db import db_array_elements, db_handler
 from simtools.io_operations import io_handler
-from simtools.layout.array_layout import ArrayLayout
+from simtools.model.site_model import SiteModel
 from simtools.model.telescope_model import TelescopeModel
 from simtools.simtel.simtel_config_writer import SimtelConfigWriter
-from simtools.utils import names
-from simtools.utils.general import collect_data_from_file_or_dict
-
-__all__ = ["ArrayModel", "InvalidArrayConfigData"]
+from simtools.utils import general, names
 
-
-class InvalidArrayConfigData(Exception):
-    """Exception for invalid array configuration data."""
+__all__ = ["ArrayModel"]
 
 
 class ArrayModel:
     """
-    ArrayModel is an abstract representation of the MC model at the array level. It contains the\
-    list of TelescopeModel's and a ArrayLayout.
+    Representation of an observatory consisting of site, telescopes, and further devices.
 
     Parameters
     ----------
     mongo_db_config: dict
         MongoDB configuration.
-    array_config_file: str
-        Path to a yaml file with the array config data.
-    array_config_data: dict
-        Dict with the array config data.
-    label: str
-        Instance label. Important for output file naming.
+    model_version: str
+        Model version.
+    label: str, optional
+        Instance label. Used for output file naming.
+    site: str, optional
+        Site name.
+    layout_name: str, optional
+        Layout name.
+    array_elements: Union[str, Path, List[str]], optional
+        Array element definitions (list of array element or path to file with
+        the array element positions).
     """
 
-    def __init__(self, mongo_db_config, label=None, array_config_file=None, array_config_data=None):
-        """
-        Initialize ArrayModel.
-        """
+    def __init__(
+        self,
+        mongo_db_config: dict,
+        model_version: str,
+        label: str | None = None,
+        site: str | None = None,
+        layout_name: str | None = None,
+        array_elements: str | Path | list[str] | None = None,
+    ):
+        """Initialize ArrayModel."""
         self._logger = logging.getLogger(__name__)
         self._logger.debug("Init ArrayModel")
         self.mongo_db_config = mongo_db_config
+        self.model_version = model_version
         self.label = label
-        self.site = None
-        self.layout = None
-        self.layout_name = None
-        self.model_version = None
+        self.layout_name = layout_name
         self._config_file_path = None
+        self._config_file_directory = None
         self.io_handler = io_handler.IOHandler()
-        array_config_data = collect_data_from_file_or_dict(array_config_file, array_config_data)
-        self._load_array_data(array_config_data)
-        self._set_config_file_directory()
-        self._build_array_model()
+        self.db = db_handler.DatabaseHandler(mongo_db_config=mongo_db_config)
+
+        self.array_elements, self.site_model, self.telescope_model = self._initialize(
+            site, array_elements
+        )
+
         self._telescope_model_files_exported = False
         self._array_model_file_exported = False
 
-    @property
-    def number_of_telescopes(self):
-        """
-        Return the number of telescopes.
-
-        Returns
-        -------
-        int
-            Number of telescopes.
+    def _initialize(self, site: str, array_elements_config: str | Path | list[str]):
         """
-        return self.layout.get_number_of_telescopes()
-
-    def _load_array_data(self, array_config_data):
-        """Load parameters from array_data.
+        Initialize ArrayModel taking different configuration options into account.
 
         Parameters
         ----------
-        array_config_data: dict
-        """
-
-        # Validating array_config_data
-        # Keys 'site', 'layout_name' and 'default' are mandatory.
-        # 'default' must have 'LST', 'MST' and 'SST' (for South site) keys.
-        self._validate_array_data(array_config_data)
-
-        # Site
-        self.site = names.validate_site_name(array_config_data["site"])
+        site: str
+            Site name.
+        array_elements_config: Union[str, Path, List[str]]
+            Array element definitions.
 
-        # Grabbing layout name and building ArrayLayout
-        self.layout_name = names.validate_array_layout_name(array_config_data["layout_name"])
-        self.layout = ArrayLayout.from_array_layout_name(
+        Returns
+        -------
+        dict
+            Dict with telescope positions.
+        SiteModel
+            Site model.
+        dict
+            Dict with telescope models.
+        """
+        self._logger.debug(f"Getting site parameters from DB ({site})")
+        site_model = SiteModel(
+            site=names.validate_site_name(site),
             mongo_db_config=self.mongo_db_config,
-            array_layout_name=self.site + "-" + self.layout_name,
+            model_version=self.model_version,
             label=self.label,
         )
 
-        # Model version
-        if (
-            "model_version" not in array_config_data.keys()
-            or array_config_data["model_version"] is None
-        ):
-            self._logger.warning("model_version not given in array_config_data - using 'Released'")
-            self.model_version = "Released"
-        else:
-            self.model_version = names.validate_model_version_name(
-                array_config_data["model_version"]
+        array_elements = {}
+        # Case 1: array_elements is a file name
+        if isinstance(array_elements_config, str | Path):
+            array_elements = self._load_array_element_positions_from_file(
+                array_elements_config, site
             )
+        # Case 2: array elements is a list of elements
+        elif isinstance(array_elements_config, list):
+            array_elements = self._get_array_elements_from_list(array_elements_config)
+        # Case 3: array elements defined in DB by array layout name
+        elif self.layout_name is not None:
+            array_elements = self._get_array_elements_from_list(
+                site_model.get_array_elements_for_layout(self.layout_name)
+            )
+        if not array_elements:
+            raise ValueError(
+                "No array elements found. "
+                "Possibly missing valid layout name or missing telescope list."
+            )
+        telescope_model = self._build_telescope_models(site_model, array_elements)
+        return array_elements, site_model, telescope_model
 
-        # Removing keys that were stored in attributes and keeping the remaining as a dict
-        self._array_config_data = {
-            k: v
-            for (k, v) in array_config_data.items()
-            if k not in ["site", "layout_name", "model_version"]
-        }
-
-    def _validate_array_data(self, array_config_data):
-        """
-        Validate array_data by checking the existence of the relevant keys. Searching for the keys:\
-        'site', 'array' and 'default'.
+    @property
+    def number_of_telescopes(self) -> int:
         """
+        Return the number of telescopes.
 
-        def run_over_pars(pars, data, parent=None):
-            """Run over pars and validate it."""
-            all_keys = data.keys() if parent is None else data[parent].keys()
-            for pp in pars:
-                if pp not in all_keys:
-                    key = pp if parent is None else parent + "." + pp
-                    msg = (
-                        f"Key {key} was not found in array_config_data "
-                        + "- impossible to build array model"
-                    )
-                    self._logger.error(msg)
-                    raise InvalidArrayConfigData(msg)
-
-        run_over_pars(["site", "layout_name", "default"], array_config_data)
-
-    def _set_config_file_directory(self):
-        """Define the variable _config_file_directory and create directories, if needed"""
-        self._config_file_directory = self.io_handler.get_output_directory(self.label, "model")
-        if not self._config_file_directory.exists():
-            self._config_file_directory.mkdir(parents=True, exist_ok=True)
-            self._logger.info(f"Creating directory {self._config_file_directory}")
-
-    def _build_array_model(self):
+        Returns
+        -------
+        int
+            Number of telescopes.
         """
-        Build the site parameters and the list of telescope models,
-        including reading the parameters from the DB.
+        return len(self.telescope_model)
 
+    @property
+    def site(self) -> str:
         """
+        Return site.
 
-        # Getting site parameters from DB
-        self._logger.debug("Getting site parameters from DB")
-        db = db_handler.DatabaseHandler(mongo_db_config=self.mongo_db_config)
-        self._site_parameters = db.get_site_parameters(
-            self.site, self.model_version, only_applicable=True
-        )
-
-        # Building telescope models
-        self._telescope_model = []  # List of telescope models
-        _all_telescope_model_names = []  # List of telescope names without repetition
-        _all_pars_to_change = {}
-        for tel in self.layout:
-            tel_size = names.get_telescope_class(tel.name)
-
-            # Collecting telescope name and pars to change from array_config_data
-            tel_model_name, pars_to_change = self._get_single_telescope_info_from_array_config(
-                tel.name, tel_size
-            )
-            if len(pars_to_change) > 0:
-                _all_pars_to_change[tel.name] = pars_to_change
-
-            self._logger.debug(f"tel_model_name: {tel_model_name}")
-
-            # Building the basic models - no pars to change yet
-            if tel_model_name not in _all_telescope_model_names:
-                # First time a telescope name is built
-                _all_telescope_model_names.append(tel_model_name)
-                tel_model = TelescopeModel(
-                    site=self.site,
-                    telescope_model_name=tel_model_name,
-                    model_version=self.model_version,
-                    label=self.label,
-                    db=db,
-                )
-            else:
-                # Telescope name already exists.
-                # Finding the TelescopeModel and copying it.
-                for tel_now in self._telescope_model:
-                    if tel_now.name != tel_model_name:
-                        continue
-                    self._logger.debug(f"Copying tel model {tel_now.name} already loaded from DB")
-                    tel_model = copy(tel_now)
-                    break
-
-            self._telescope_model.append(tel_model)
-
-        # Checking whether the size of the telescope list and the layout match
-        if len(self._telescope_model) != len(self.layout):
-            self._logger.warning(
-                "Number of telescopes in the list of telescope models does "
-                "not match the number of telescopes in the ArrayLayout - something is wrong!"
-            )
-
-        # Changing parameters, if there are any in all_pars_to_change
-        if len(_all_pars_to_change) > 0:
-            for tel_data, tel_model in zip(self.layout, self._telescope_model):
-                if tel_data.name not in _all_pars_to_change:
-                    continue
-                self._logger.debug(
-                    f"Changing {len(_all_pars_to_change[tel_data.name])} pars of a "
-                    f"{tel_data.name}: {*_all_pars_to_change[tel_data.name],}, ..."
-                )
-                tel_model.change_multiple_parameters(**_all_pars_to_change[tel_data.name])
-                tel_model.set_extra_label(tel_data.name)
+        Returns
+        -------
+        str
+            Site name.
+        """
+        return self.site_model.site
 
-    def _get_single_telescope_info_from_array_config(self, tel_name, tel_size):
+    def _build_telescope_models(self, site_model: SiteModel, array_elements: dict) -> dict:
         """
-        array_config_data contains the default telescope models for each telescope size and the \
-        list of specific telescopes. For each case, the data can be given only as a name or as a \
-        dict with 'name' and parameters to change. This function has to identify these two cases\
-        and collect the telescope name and the dict with the parameters to change.
+        Build the the telescope models for all telescopes of this array.
+
+        Includes reading of telescope model parameters from the DB.
+        The array is defined in the telescopes dictionary. Array element positions
+        are read from the database if no values are given in this dictionary.
 
         Parameters
         ----------
-        tel_name: str
-            Name of the telescope at the layout level (LST-01, MST-05, ...).
-        tel_size: str
-            LST, MST or SST.
-        """
+        site_model: SiteModel
+            Site model.
+        array_elements: dict
+            Dict with array elements.
 
-        def _proccess_single_telescope(data):
-            """
-            Parameters
-            ----------
-            data: dict or str
-                Piece of the array_config_data for one specific telescope.
-            """
-
-            if isinstance(data, dict):
-                # Case 0: data is dict
-                if "name" not in data.keys():
-                    msg = "ArrayConfig has no name for a telescope"
-                    self._logger.error(msg)
-                    raise InvalidArrayConfigData(msg)
-                tel_name = tel_size + "-" + data["name"]
-                pars_to_change = {k: v for (k, v) in data.items() if k != "name"}
-                self._logger.debug(
-                    "Grabbing tel data as dict - "
-                    f"name: {tel_name}, "
-                    f"{len(pars_to_change)} pars to change"
+        Returns
+        -------
+        dict
+            Dictionary with telescope models.
+        """
+        telescope_model = {}
+        for element_name, _ in array_elements.items():
+            collection = names.get_collection_name_from_array_element_name(element_name)
+            if collection == "telescopes":
+                telescope_model[element_name] = TelescopeModel(
+                    site=site_model.site,
+                    telescope_name=element_name,
+                    model_version=self.model_version,
+                    mongo_db_config=self.mongo_db_config,
+                    label=self.label,
                 )
-                return tel_name, pars_to_change
-            if isinstance(data, str):
-                # Case 1: data is string (only name)
-                tel_name = tel_size + "-" + data
-                return tel_name, {}
-
-            # Case 2: data has a wrong type
-            msg = "ArrayConfig has wrong input for a telescope"
-            self._logger.error(msg)
-            raise InvalidArrayConfigData(msg)
-
-        if tel_name in self._array_config_data.keys():
-            # Specific info for this telescope
-            return _proccess_single_telescope(self._array_config_data[tel_name])
-
-        # Checking if default option exists in array_config_data
-        not_contains_default_key = (
-            "default" not in self._array_config_data.keys()
-            or tel_size not in self._array_config_data["default"].keys()
-        )
-
-        if not_contains_default_key:
-            msg = (
-                "default option was not given in array_config_data "
-                + f"for the telescope {tel_name}"
-            )
-            self._logger.error(msg)
-            raise InvalidArrayConfigData(msg)
-
-        # Grabbing the default option
-        return _proccess_single_telescope(self._array_config_data["default"][tel_size])
+        return telescope_model
 
     def print_telescope_list(self):
-        """Print out the list of telescopes for quick inspection."""
-
-        for tel_data, tel_model in zip(self.layout, self._telescope_model):
-            print(f"Name: {tel_data.name}\t Model: {tel_model.name}")
+        """Print list of telescopes."""
+        for tel_name, data in self.telescope_model.items():
+            print(f"Name: {tel_name}\t Model: {data.name}")
 
     def export_simtel_telescope_config_files(self):
-        """
-        Export sim_telarray config files for all the telescopes into the output model directory.
-        """
-
+        """Export sim_telarray configuration files for all telescopes into the model directory."""
         exported_models = []
-        for tel_model in self._telescope_model:
+        for _, tel_model in self.telescope_model.items():
             name = tel_model.name + (
                 "_" + tel_model.extra_label if tel_model.extra_label != "" else ""
             )
             if name not in exported_models:
-                self._logger.debug(f"Exporting config file for tel {name}")
+                self._logger.debug(f"Exporting configuration file for telescope {name}")
                 tel_model.export_config_file()
                 exported_models.append(name)
             else:
-                self._logger.debug(f"Config file for tel {name} already exists - skipping")
+                self._logger.debug(
+                    f"Configuration file for telescope {name} already exists - skipping"
+                )
 
         self._telescope_model_files_exported = True
 
     def export_simtel_array_config_file(self):
-        """
-        Export sim_telarray config file for the array into the output model directory.
-        """
-
+        """Export sim_telarray configuration file for the array into the model directory."""
         # Setting file name and the location
-        config_file_name = names.simtel_array_config_file_name(
-            self.layout_name, self.site, self.model_version, self.label
+        config_file_name = names.simtel_config_file_name(
+            array_name=self.layout_name,
+            site=self.site_model.site,
+            model_version=self.model_version,
+            label=self.label,
         )
-        self._config_file_path = self._config_file_directory.joinpath(config_file_name)
+        self._config_file_path = self.get_config_directory().joinpath(config_file_name)
 
         # Writing parameters to the file
-        self._logger.info(f"Writing array config file into {self._config_file_path}")
+        self._logger.info(f"Writing array configuration file into {self._config_file_path}")
         simtel_writer = SimtelConfigWriter(
-            site=self.site,
+            site=self.site_model.site,
             layout_name=self.layout_name,
             model_version=self.model_version,
             label=self.label,
         )
         simtel_writer.write_array_config_file(
             config_file_path=self._config_file_path,
-            layout=self.layout,
-            telescope_model=self._telescope_model,
-            site_parameters=self._site_parameters,
+            telescope_model=self.telescope_model,
+            site_model=self.site_model,
         )
         self._array_model_file_exported = True
 
     def export_all_simtel_config_files(self):
         """
-        Export sim_telarray config file for the array and for each individual telescope into the \
-        output model directory.
-        """
+        Export sim_telarray config file for the array and for each individual telescope.
 
+        Config files are exported into the output model directory.
+        """
         if not self._telescope_model_files_exported:
             self.export_simtel_telescope_config_files()
         if not self._array_model_file_exported:
             self.export_simtel_array_config_file()
 
-    def get_config_file(self):
+    def get_config_file(self) -> Path:
         """
-        Get the path of the array config file for sim_telarray. The config file is produced if the \
-        file is not updated.
+        Return the path of the array config file for sim_telarray.
+
+        A new config file is produced if the file is not updated.
 
         Returns
         -------
         Path
             Path of the exported config file for sim_telarray.
         """
-
         self.export_all_simtel_config_files()
         return self._config_file_path
 
-    def get_config_directory(self):
+    def get_config_directory(self) -> Path:
         """
         Get the path of the array config directory for sim_telarray.
 
@@ -363,4 +256,164 @@ class ArrayModel:
         Path
             Path of the config directory path for sim_telarray.
         """
+        if self._config_file_directory is None:
+            self._config_file_directory = self.io_handler.get_output_directory(self.label, "model")
         return self._config_file_directory
+
+    def _load_array_element_positions_from_file(
+        self, array_elements_file: str | Path, site: str
+    ) -> dict:
+        """
+        Load array element (e.g. telescope) positions from a file into a dict.
+
+        Dictionary format: {telescope_name: {position_x: x, position_y: y, position_z: z}}
+
+        Parameters
+        ----------
+        array_elements_file: Union[str, Path]
+            Path to the file with the array element positions.
+        site: str
+            Site name.
+
+        Returns
+        -------
+        dict
+            Dict with telescope positions.
+        """
+        table = data_reader.read_table_from_file(file_name=array_elements_file)
+
+        return {
+            row["telescope_name"]: self._get_telescope_position_parameter(
+                row["telescope_name"], site, row["position_x"], row["position_y"], row["position_z"]
+            )
+            for row in table
+        }
+
+    def _get_telescope_position_parameter(
+        self, telescope_name: str, site: str, x: u.Quantity, y: u.Quantity, z: u.Quantity
+    ) -> dict:
+        """
+        Return dictionary with telescope position parameters (following DB model database format).
+
+        Parameters
+        ----------
+        telescope_name: str
+            Name of the telescope.
+        site: str
+            Site name.
+        x: astropy.Quantity
+            X ground position.
+        y: astropy.Quantity
+            Y ground position.
+        z: astropy.Quantity
+            Z ground position.
+
+        Returns
+        -------
+        dict
+            Dict with telescope position parameters.
+        """
+        return {
+            "parameter": "array_element_position_ground",
+            "instrument": telescope_name,
+            "site": site,
+            "version": self.model_version,
+            "value": general.convert_list_to_string(
+                [x.to("m").value, y.to("m").value, z.to("m").value]
+            ),
+            "unit": "m",
+            "type": "float64",
+            "applicable": True,
+            "file": False,
+        }
+
+    def _get_array_elements_from_list(self, array_elements_list: list[str]) -> dict:
+        """
+        Return dictionary with array elements from a list of telescope names.
+
+        Input list can contain telescope names (e.g, LSTN-01) or a telescope
+        type (e.g., MSTN). In the latter case, all telescopes of this specific
+        type are added.
+
+        Parameters
+        ----------
+        array_elements_list: list
+            List of telescope names.
+
+        Returns
+        -------
+        dict
+            Dict with array elements.
+        """
+        array_elements_dict = {}
+        for name in array_elements_list:
+            try:
+                array_elements_dict[names.validate_array_element_name(name)] = None
+            except ValueError:
+                array_elements_dict.update(self._get_all_array_elements_of_type(name))
+        return array_elements_dict
+
+    def _get_all_array_elements_of_type(self, array_element_type: str) -> dict:
+        """
+        Return all array elements of a specific type using the database.
+
+        Parameters
+        ----------
+        array_element_type : str
+            Type of the array element (e.g. LSTN, MSTS)
+
+        Returns
+        -------
+        dict
+            Dict with array elements.
+        """
+        all_elements = db_array_elements.get_array_elements_of_type(
+            array_element_type=array_element_type,
+            db=self.db,
+            model_version=self.model_version,
+            collection="telescopes",
+        )
+        return self._get_array_elements_from_list(all_elements)
+
+    def export_array_elements_as_table(self, coordinate_system: str = "ground") -> QTable:
+        """
+        Export array elements positions to astropy table.
+
+        Parameters
+        ----------
+        coordinate_system: str
+            Positions are exported in this coordinate system.
+
+        Returns
+        -------
+        astropy.table.QTable
+            Astropy table with the telescope layout information.
+        """
+        table = QTable(meta={"array_name": self.layout_name, "site": self.site_model.site})
+
+        name, pos_x, pos_y, pos_z, tel_r = [], [], [], [], []
+        for tel_name, data in self.telescope_model.items():
+            name.append(tel_name)
+            xyz = data.position(coordinate_system=coordinate_system)
+            pos_x.append(xyz[0])
+            pos_y.append(xyz[1])
+            pos_z.append(xyz[2])
+            try:
+                # add tests of KeyError after positions calibration_elements are added to DB
+                tel_r.append(data.get_parameter_value_with_unit("telescope_sphere_radius"))
+            except KeyError:  # not all array elements have a sphere radius
+                tel_r.append(0.0 * u.m)
+
+        table["telescope_name"] = name
+        if coordinate_system == "ground":
+            table["position_x"] = pos_x
+            table["position_y"] = pos_y
+            table["position_z"] = pos_z
+        elif coordinate_system == "utm":
+            table["utm_east"] = pos_x
+            table["utm_north"] = pos_y
+            table["altitude"] = pos_z
+        table["sphere_radius"] = tel_r
+
+        table.sort("telescope_name")
+        return table