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

simtools/utils/names.py

@@ -1,28 +1,30 @@
 import logging
+import re
 
 _logger = logging.getLogger(__name__)
 
 __all__ = [
+    "array_element_id_from_telescope_model_name",
     "camera_efficiency_log_file_name",
     "camera_efficiency_results_file_name",
     "camera_efficiency_simtel_file_name",
-    "convert_telescope_model_name_to_yaml",
+    "convert_telescope_model_name_to_yaml_name",
     "get_site_from_telescope_name",
-    "get_telescope_type",
-    "is_valid_name",
+    "get_telescope_class",
     "layout_telescope_list_file_name",
     "ray_tracing_file_name",
     "ray_tracing_plot_file_name",
     "ray_tracing_results_file_name",
+    "sanitize_name",
     "simtel_array_config_file_name",
+    "simtel_single_mirror_list_file_name",
     "simtel_telescope_config_file_name",
-    "simtools_instrument_name",
+    "get_telescope_name_db",
     "split_telescope_model_name",
-    "validate_camera_name",
-    "validate_layout_array_name",
+    "telescope_model_name_from_array_element_id",
+    "translate_simtools_to_corsika",
+    "validate_array_layout_name",
     "validate_model_version_name",
-    "validate_name",
-    "validate_simtel_mode_name",
     "validate_site_name",
     "validate_sub_system_name",
     "validate_telescope_id_name",
@@ -34,28 +36,40 @@ lst = "LST"
 mst = "MST"
 sct = "SCT"
 sst = "SST"
+hess = "HESS"
+magic = "MAGIC"
+veritas = "VERITAS"
 
 all_telescope_class_names = {
     lst: ["lst"],
     mst: ["mst"],
     sct: ["sct"],
     sst: ["sst"],
+    hess: ["hess"],
+    magic: ["magic"],
+    veritas: ["veritas"],
 }
 
-all_camera_names = {
-    "SST": ["sst"],
+all_subsystem_names = {
+    "SST": ["sst", "ssts", "SSTS"],
     "ASTRI": ["astri"],
     "GCT": ["gct", "gct-s"],
     "1M": ["1m"],
-    "FlashCam": ["flashcam", "flash-cam"],
-    "NectarCam": ["nectarcam", "nectar-cam"],
-    "SCT": ["sct"],
-    "LST": ["lst"],
+    "FlashCam": ["flashcam", "flash-cam", "msts", "MSTS"],
+    "NectarCam": ["nectarcam", "nectar-cam", "mstn", "MSTN"],
+    "SCT": ["sct", "scts", "SCTS"],
+    "LST": ["lst", "lsts", "LSTS", "lstn", "LSTN"],
+    "Camera": ["Camera", "camera"],
+    "Structure": ["Structure", "structure"],
+    "MAGIC": ["magic", "MAGIC"],
+    "VERITAS": ["veritas", "VERITAS"],
+    "HESS": ["hess", "HESS"],
 }
 
-all_structure_names = {"Structure": ["Structure", "structure"]}
-
-all_site_names = {"South": ["paranal", "south"], "North": ["lapalma", "north"]}
+all_site_names = {
+    "South": ["paranal", "south", "cta-south", "ctao-south", "s"],
+    "North": ["lapalma", "north", "cta-north", "ctao-north", "n"],
+}
 
 all_model_version_names = {
     "2015-07-21": [""],
@@ -76,21 +90,11 @@ all_model_version_names = {
     "2020-06-28": ["prod5"],
     "prod4-prototype": [""],
     "default": [],
-    "Current": [],
+    "Released": [],
     "Latest": [],
 }
 
-all_simtel_mode_names = {
-    "RayTracing": ["raytracing", "ray-tracing"],
-    "RayTracingSingleMirror": [
-        "raytracing-singlemirror",
-        "ray-tracing-singlemirror",
-        "ray-tracing-single-mirror",
-    ],
-    "Trigger": ["trigger"],
-}
-
-all_layout_array_names = {
+all_array_layout_names = {
     "4LST": ["4-lst", "4lst"],
     "1LST": ["1-lst", "1lst"],
     "4MST": ["4-mst", "4mst"],
@@ -101,8 +105,16 @@ all_layout_array_names = {
     "TestLayout": ["test-layout"],
 }
 
-corsika_to_simtools_names = {
-    "OBSLEV": "corsika_obs_level",
+# array elements as defined by CTAO
+# (includes for now only telescopes;
+# can be extended to other elements)
+all_array_element_id_names = {
+    "lstn": ["LSTN", "lstn"],
+    "mstn": ["MSTN", "mstn"],
+    "lsts": ["LSTS", "lsts"],
+    "msts": ["MSTS", "msts"],
+    "ssts": ["SSTS", "ssts"],
+    "scts": ["SCTS", "scts"],
 }
 
 
@@ -120,24 +132,24 @@ def validate_sub_system_name(name):
     str
         Validated name.
     """
-    return validate_name(name, {**all_camera_names, **all_structure_names})
+    return _validate_name(name, all_subsystem_names)
 
 
-def validate_camera_name(name):
+def validate_telescope_class_name(name):
     """
-    Validate a camera name.
+    Validate a telescope class name (LST, MST, SST, ...).
 
     Parameters
     ----------
     name: str
-        Camera name
+        Telescope class name.
 
     Returns
     -------
     str
         Validated name.
     """
-    return validate_name(name, all_camera_names)
+    return _validate_name(name, all_telescope_class_names)
 
 
 def validate_telescope_id_name(name):
@@ -146,11 +158,11 @@ def validate_telescope_id_name(name):
 
     Valid names e.g.,
     - D
-    - telescope ID
+    - telescope ID (e.g., 1, 5, 15)
 
     Parameters
     ----------
-    name: str
+    name: str or int
         Telescope ID name.
 
     Returns
@@ -164,8 +176,8 @@ def validate_telescope_id_name(name):
         If name is not valid.
     """
 
-    if name == "D" or name.isdigit():
-        return name
+    if isinstance(name, int) or name.upper() in ("D", "D234", "TEST") or name.isdigit():
+        return str(name).upper()
 
     msg = f"Invalid telescope ID name {name}"
     _logger.error(msg)
@@ -186,24 +198,7 @@ def validate_model_version_name(name):
     str
         Validated name.
     """
-    return validate_name(name, all_model_version_names)
-
-
-def validate_simtel_mode_name(name):
-    """
-    Validate a sim_telarray mode name.
-
-    Parameters
-    ----------
-    name: str
-        sim_telarray mode name.
-
-    Returns
-    -------
-    str
-        Validated name.
-    """
-    return validate_name(name, all_simtel_mode_names)
+    return _validate_name(name, all_model_version_names)
 
 
 def validate_site_name(name):
@@ -220,12 +215,12 @@ def validate_site_name(name):
     str
         Validated name.
     """
-    return validate_name(name, all_site_names)
+    return _validate_name(name, all_site_names)
 
 
-def validate_layout_array_name(name):
+def validate_array_layout_name(name):
     """
-    Validate a layout array name.
+    Validate a array layout name.
 
     Parameters
     ----------
@@ -237,10 +232,10 @@ def validate_layout_array_name(name):
     str
         Validated name.
     """
-    return validate_name(name, all_layout_array_names)
+    return _validate_name(name, all_array_layout_names)
 
 
-def validate_name(name, all_names):
+def _validate_name(name, all_names):
     """
     Validate a name given the all_names options. For each key in all_names, a list of options is \
     given. If name is in this list, the key name is returned.
@@ -262,7 +257,7 @@ def validate_name(name, all_names):
         If name is not valid.
     """
 
-    if not is_valid_name(name, all_names):
+    if not _is_valid_name(name, all_names):
         msg = f"Invalid name {name}"
         raise ValueError(msg)
     for main_name, list_of_names in all_names.items():
@@ -273,7 +268,7 @@ def validate_name(name, all_names):
     return None
 
 
-def is_valid_name(name, all_names):
+def _is_valid_name(name, all_names):
     """
     Check if name is valid.
 
@@ -313,27 +308,27 @@ def validate_telescope_model_name(name):
         Validated name.
     """
 
-    tel_class, tel_type = split_telescope_model_name(name)
-    tel_class = validate_name(tel_class, all_telescope_class_names)
-    if "flashcam" in tel_type:
-        tel_type = tel_type.replace("flashcam", "FlashCam")
-    if "nectarcam" in tel_type:
-        tel_type = tel_type.replace("nectarcam", "NectarCam")
-    if "1m" in tel_type:
-        tel_type = tel_type.replace("1m", "1M")
-    if "gct" in tel_type:
-        tel_type = tel_type.replace("gct", "GCT")
-    if "astri" in tel_type:
-        tel_type = tel_type.replace("astri", "ASTRI")
-    if "-d" in "-" + tel_type:
-        tel_type = tel_type.replace("d", "D")
+    # e.g, MSTN or MSTN-01
+    try:
+        return _validate_name(name, all_array_element_id_names)
+    except ValueError:
+        pass
 
-    return tel_class + "-" + tel_type
+    # e.g., MST-FlashCam or MST-FlashCam-01
+    tel_class, tel_type, tel_id = split_telescope_model_name(name)
+    _telescope_name = tel_class
+    if tel_class != tel_type and len(tel_type) > 0:
+        _telescope_name += "-" + tel_type
+    if len(tel_id) > 0:
+        _telescope_name += "-" + tel_id
+    return _telescope_name
 
 
 def split_telescope_model_name(name):
     """
-    Split a telescope name into class and type.
+    Split a telescope name into class, type, telescope id.
+    Allow various inputs, e.g., MST-FlashCam-01, MST-FlashCam,
+    MSTN-01, MSTN, MST-1
 
     Parameters
     ----------
@@ -342,14 +337,44 @@ def split_telescope_model_name(name):
 
     Returns
     -------
-    str, str
-       class (LST, MST, SST ...) and type (any complement).
+    str, str, str
+       class (LST, MST, SST ...), type (any complement), telescope id
     """
-
     name_parts = name.split("-")
+    # e.g., MSTN or MSTN-01
+    try:
+        _is_valid_name(name_parts[0], all_array_element_id_names)
+        return (
+            validate_telescope_class_name(name_parts[0][0:3]),
+            validate_sub_system_name(name_parts[0]),
+            validate_telescope_id_name(name_parts[1]) if len(name_parts) > 1 else "",
+        )
+    except ValueError:
+        pass
+
+    # e.g., MST-FlashCam or MST-FlashCam-01, MST-1
+    # (note that this complicated, as LST-1 is a valid
+    # name without explicit subsystem given in name)
     tel_class = name_parts[0]
-    tel_type = "-".join(name_parts[1:])
-    return tel_class, tel_type
+    try:
+        tel_id = validate_telescope_id_name(name_parts[-1])
+        _tmp_tel_type = name_parts[1:-1]
+    except ValueError:
+        tel_id = ""
+        _tmp_tel_type = name_parts[1:]
+    if len(_tmp_tel_type) > 0:
+        tel_type = "-".join(_tmp_tel_type)
+    else:
+        try:
+            tel_type = validate_sub_system_name(tel_class)
+        except ValueError:
+            tel_type = ""
+
+    return (
+        validate_telescope_class_name(tel_class),
+        validate_sub_system_name(tel_type) if len(tel_type) > 0 else "",
+        validate_telescope_id_name(tel_id) if len(tel_id) > 0 else "",
+    )
 
 
 def get_site_from_telescope_name(name):
@@ -366,12 +391,20 @@ def get_site_from_telescope_name(name):
     str
         Site name (South or North).
     """
+    # e.g, MSTN or MSTN-01 (tested by get_telescope_class)
+    try:
+        get_telescope_class(name)
+        return validate_site_name(name[3])
+    except ValueError:
+        pass
+    # e.g., South-MST-FlashCam
     return validate_site_name(name.split("-")[0])
 
 
 def validate_telescope_name_db(name):
     """
     Validate a telescope DB name.
+    Examples are North-LST-1, North-MST-NectarCam-D, or South-SST-Structure-D.
 
     Parameters
     ----------
@@ -388,7 +421,7 @@ def validate_telescope_name_db(name):
     return f"{validate_site_name(site)}-{validate_telescope_model_name(tel_model_name)}"
 
 
-def convert_telescope_model_name_to_yaml(name):
+def convert_telescope_model_name_to_yaml_name(name):
     """
     Get telescope name following the old convention (yaml files) from the current telescope name.
 
@@ -407,8 +440,9 @@ def convert_telescope_model_name_to_yaml(name):
     ValueError
         if name is not valid.
     """
-    tel_class, tel_type = split_telescope_model_name(name)
-    new_name = tel_class + "-" + tel_type
+    tel_class, tel_type, tel_id = split_telescope_model_name(name)
+    new_name = tel_class if tel_class == tel_type else tel_class + "-" + tel_type
+    new_name = new_name + "-" + tel_id if len(tel_id) > 0 else new_name
     old_names = {
         "SST-D": "SST",
         "SST-1M": "SST-1M",
@@ -422,14 +456,97 @@ def convert_telescope_model_name_to_yaml(name):
     }
 
     if new_name not in old_names:
-        raise ValueError(f"Telescope name {name} could not be converted to yml names")
+        raise ValueError(f"Telescope name {name}/{new_name} could not be converted to yml names")
 
     return old_names[new_name]
 
 
-def simtools_instrument_name(site, telescope_class_name, sub_system_name, telescope_id_name):
+def array_element_id_from_telescope_model_name(site, telescope_model_name):
+    """
+    Array element ID (CTAO convention) from telescope model name.
+    This returns e.g., "LSTN" for any LST telescope in the North site.
+    If a telescope number is given, it adds it as e.g., "LSTN-01".
+
+    Parameters
+    ----------
+    site: str
+        Observatory site (e.g., South or North)
+    telescope_class_name: str
+        Name of the telescope class (e.g. LST-1, LST-D234, MST-FlashCam-D, ...)
+
+    Returns
+    -------
+    str
+        Array element ID (CTAO style).
+
+    """
+
+    _class, _type, _tel_id = split_telescope_model_name(telescope_model_name)
+    _id = _class.upper() + site[0].upper()
+    if _tel_id.isdigit():
+        _id += f"-{int(_tel_id):02d}"
+    return _id
+
+
+def telescope_model_name_from_array_element_id(
+    array_element_id, sub_system_name="structure", available_telescopes=None
+):
+    """
+    Telescope model name from array element ID (CTAO convention).
+    Does not include the site in the returned name (e.g., returns
+    South-MST-FlashCam-1 for MSTS-01; this method is quite finetuned).
+
+    Parameters
+    ----------
+    array_element_id: str
+        Array element ID (CTAO convention).
+    available_telescopes: list
+        List of available telescopes.
+
+    Returns
+    -------
+    str
+        Telescope model name.
+    """
+
+    name_parts = array_element_id.split("-")
+    try:
+        _class = name_parts[0][0:3]
+        _site = validate_site_name(name_parts[0][3])
+    except IndexError as exc:
+        _logger.error("Invalid array element ID %s", array_element_id)
+        raise exc
+    try:
+        _id = int(name_parts[1])
+    except (ValueError, IndexError):
+        _id = "D"
+
+    if _class in ("LST", "SCT"):
+        sub_system_name = None
+    elif _class == "MST" and sub_system_name.lower() == "camera":
+        sub_system_name = "NectarCam" if _site == "North" else "FlashCam"
+
+    _simtools_name = get_telescope_name_db(
+        site=_site,
+        telescope_class_name=_class,
+        sub_system_name=sub_system_name,
+        telescope_id_name=_id,
+    )
+    if available_telescopes is not None and _simtools_name not in available_telescopes:
+        _logger.debug("Telescope %s not available", _simtools_name)
+        _simtools_name = get_telescope_name_db(
+            site=_site,
+            telescope_class_name=_class,
+            sub_system_name=sub_system_name,
+            telescope_id_name="D234" if _site == "North" and _class == "LST" else "D",
+        )
+    return _simtools_name.split("-", 1)[1]
+
+
+def get_telescope_name_db(site, telescope_class_name, sub_system_name, telescope_id_name):
     """
     Instrument name following simtools naming convention
+    Examples are North-LST-1, North-MST-NectarCam-D, or South-SST-Structure-D.
 
     Parameters
     ----------
@@ -437,8 +554,8 @@ def simtools_instrument_name(site, telescope_class_name, sub_system_name, telesc
         South or North.
     telescope_class_name: str
         LST, MST, ...
-    sub_system_name: str
-        FlashCam, NectarCam
+    sub_system_name: str or None
+        FlashCam, NectarCam, Structure
     telescope_id_name: str
         telescope ID (e.g., D, numerical value)
 
@@ -451,9 +568,8 @@ def simtools_instrument_name(site, telescope_class_name, sub_system_name, telesc
     return (
         validate_site_name(site)
         + "-"
-        + validate_name(telescope_class_name, all_telescope_class_names)
-        + "-"
-        + validate_sub_system_name(sub_system_name)
+        + _validate_name(telescope_class_name, all_telescope_class_names)
+        + ("" if sub_system_name is None else "-" + validate_sub_system_name(sub_system_name))
         + "-"
         + validate_telescope_id_name(telescope_id_name)
     )
@@ -490,7 +606,7 @@ def simtel_telescope_config_file_name(
     return name
 
 
-def simtel_array_config_file_name(array_name, site, version, label):
+def simtel_array_config_file_name(array_name, site, model_version, label):
     """
     sim_telarray config file name for an array.
 
@@ -500,7 +616,7 @@ def simtel_array_config_file_name(array_name, site, version, label):
         Prod5, ...
     site: str
         South or North.
-    version: str
+    model_version: str
         Version of the model.
     label: str
         Instance label.
@@ -510,7 +626,7 @@ def simtel_array_config_file_name(array_name, site, version, label):
     str
         File name.
     """
-    name = f"CTA-{array_name}-{site}-{version}"
+    name = f"CTA-{array_name}-{site}-{model_version}"
     name += f"_{label}" if label is not None else ""
     name += ".cfg"
     return name
@@ -679,7 +795,9 @@ def ray_tracing_plot_file_name(
     return name
 
 
-def camera_efficiency_results_file_name(site, telescope_model_name, zenith_angle, label):
+def camera_efficiency_results_file_name(
+    site, telescope_model_name, zenith_angle, azimuth_angle, label
+):
     """
     Camera efficiency results file name.
 
@@ -691,6 +809,8 @@ def camera_efficiency_results_file_name(site, telescope_model_name, zenith_angle
         LST-1, MST-FlashCam, ...
     zenith_angle: float
         Zenith angle (deg).
+    azimuth_angle: float
+        Azimuth angle (deg).
     label: str
         Instance label.
 
@@ -699,13 +819,18 @@ def camera_efficiency_results_file_name(site, telescope_model_name, zenith_angle
     str
         File name.
     """
-    name = f"camera-efficiency-{site}-{telescope_model_name}-za{zenith_angle:.1f}"
-    name += f"_{label}" if label is not None else ""
-    name += ".ecsv"
+    _label = f"_{label}" if label is not None else ""
+    name = (
+        f"camera-efficiency-table-{site}-{telescope_model_name}-"
+        f"za{round(zenith_angle):03}deg_azm{round(azimuth_angle):03}deg"
+        f"{_label}.ecsv"
+    )
     return name
 
 
-def camera_efficiency_simtel_file_name(site, telescope_model_name, zenith_angle, label):
+def camera_efficiency_simtel_file_name(
+    site, telescope_model_name, zenith_angle, azimuth_angle, label
+):
     """
     Camera efficiency simtel output file name.
 
@@ -717,6 +842,8 @@ def camera_efficiency_simtel_file_name(site, telescope_model_name, zenith_angle,
         LST-1, MST-FlashCam-D, ...
     zenith_angle: float
         Zenith angle (deg).
+    azimuth_angle: float
+        Azimuth angle (deg).
     label: str
         Instance label.
 
@@ -725,13 +852,16 @@ def camera_efficiency_simtel_file_name(site, telescope_model_name, zenith_angle,
     str
         File name.
     """
-    name = f"camera-efficiency-{site}-{telescope_model_name}-za{zenith_angle:.1f}"
-    name += f"_{label}" if label is not None else ""
-    name += ".dat"
+    _label = f"_{label}" if label is not None else ""
+    name = (
+        f"camera-efficiency-{site}-{telescope_model_name}-"
+        f"za{round(zenith_angle):03}deg_azm{round(azimuth_angle):03}deg"
+        f"{_label}.dat"
+    )
     return name
 
 
-def camera_efficiency_log_file_name(site, telescope_model_name, zenith_angle, label):
+def camera_efficiency_log_file_name(site, telescope_model_name, zenith_angle, azimuth_angle, label):
     """
     Camera efficiency log file name.
 
@@ -743,6 +873,8 @@ def camera_efficiency_log_file_name(site, telescope_model_name, zenith_angle, la
         LST-1, MST-FlashCam-D, ...
     zenith_angle: float
         Zenith angle (deg).
+    azimuth_angle: float
+        Azimuth angle (deg).
     label: str
         Instance label.
 
@@ -751,15 +883,18 @@ def camera_efficiency_log_file_name(site, telescope_model_name, zenith_angle, la
     str
         File name.
     """
-    name = f"camera-efficiency-{site}-{telescope_model_name}-za{zenith_angle:.1f}"
-    name += f"_{label}" if label is not None else ""
-    name += ".log"
+    _label = f"_{label}" if label is not None else ""
+    name = (
+        f"camera-efficiency-{site}-{telescope_model_name}"
+        f"-za{round(zenith_angle):03}deg_azm{round(azimuth_angle):03}deg"
+        f"{_label}.log"
+    )
     return name
 
 
-def get_telescope_type(telescope_name):
+def get_telescope_class(telescope_name):
     """
-    Guess telescope type from name, e.g. "LST", "MST", ...
+    Guess telescope class from name, e.g. "LST", "MST", ...
 
     Parameters
     ----------
@@ -772,47 +907,24 @@ def get_telescope_type(telescope_name):
         Telescope type.
     """
 
-    _class, _ = split_telescope_model_name(telescope_name)
-    try:
-        if _class[0:3] in all_telescope_class_names:
-            return _class[0:3]
-
-    except IndexError:
-        pass
-
-    return ""
-
-
-def translate_corsika_to_simtools(corsika_par):
-    """
-    Translate the name of a CORSIKA parameter to the name used in simtools.
-
-    Parameters
-    ----------
-    corsika_par: str
-        Name of the corsika parameter to be translated.
-
-    """
-
-    try:
-        return corsika_to_simtools_names[corsika_par]
-    except KeyError:
-        msg = f"Translation not found. We will proceed with the original parameter name:\
-            {corsika_par}."
-        _logger.debug(msg)
-        return corsika_par
+    _tel_class, _, _ = split_telescope_model_name(telescope_name)
+    return _tel_class
 
 
 def translate_simtools_to_corsika(simtools_par):
     """
     Translate the name of a simtools parameter to the name used in CORSIKA.
 
+    TODO - this will go with the new simulation model
+
     Parameters
     ----------
     simtools_par: str
         Name of the simtools parameter to be translated.
     """
 
+    corsika_to_simtools_names = {"OBSLEV": "corsika_obs_level"}
+
     simtools_to_corsika_names = {
         new_key: new_value for new_value, new_key in corsika_to_simtools_names.items()
     }
@@ -823,3 +935,43 @@ def translate_simtools_to_corsika(simtools_par):
             {simtools_par}."
         _logger.debug(msg)
         return simtools_par
+
+
+def sanitize_name(name):
+    """
+    Sanitize name to be a valid Python identifier.
+
+    - Replaces spaces with underscores
+    - Converts to lowercase
+    - Removes characters that are not alphanumerics or underscores
+    - If the name starts with a number, prepend an underscore
+
+    Parameters
+    ----------
+    name: str
+        name to be sanitized.
+
+    Returns
+    -------
+    str:
+        Sanitized name.
+
+    Raises
+    ------
+    ValueError:
+        if the string `name` can not be sanitized.
+    """
+
+    # Convert to lowercase
+    sanitized = name.lower()
+
+    # Replace spaces with underscores
+    sanitized = sanitized.replace(" ", "_")
+
+    # Remove characters that are not alphanumerics or underscores
+    sanitized = re.sub(r"\W|^(?=\d)", "_", sanitized)
+    if not sanitized.isidentifier():
+        msg = f"The string {name} could not be sanitized."
+        _logger.error(msg)
+        raise ValueError
+    return sanitized