gammasimtools 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

simtools/utils/names.py

@@ -1,20 +1,32 @@
-"""Validation of names."""
+"""Name utilities for array elements, sites, and model parameters.
+
+Naming in simtools:
+
+* 'site': South or North
+* 'array element': e.g., LSTN-01, MSTN-01, ...
+* 'array element type': e.g., LSTN, MSTN, ...
+* 'array element ID': e.g., 01, 02, ...
+* 'array element design type': e.g., design, test
+* 'instrument class key': e.g., telescope, camera, structure
+* 'db collection': e.g., telescopes, sites, calibration_devices
+
+"""
 
 import logging
 import re
 from functools import cache
-from importlib.resources import files
 from pathlib import Path
 
 import yaml
 
+from simtools.constants import MODEL_PARAMETER_SCHEMA_PATH, SCHEMA_PATH
+
 _logger = logging.getLogger(__name__)
 
 __all__ = [
     "generate_file_name",
     "get_array_element_type_from_name",
     "get_site_from_array_element_name",
-    "layout_telescope_list_file_name",
     "sanitize_name",
     "simtel_config_file_name",
     "simtel_single_mirror_list_file_name",
@@ -23,68 +35,170 @@ __all__ = [
     "validate_site_name",
 ]
 
+# Mapping of db collection names to class keys
+db_collections_to_class_keys = {
+    "sites": ["Site"],
+    "telescopes": ["Structure", "Camera", "Telescope"],
+    "calibration_devices": ["Calibration"],
+    "configuration_sim_telarray": ["configuration_sim_telarray"],
+    "configuration_corsika": ["configuration_corsika"],
+}
+
 
 @cache
 def array_elements():
     """
-    Load array elements from reference files and keep in cache.
+    Get array elements and their properties.
 
     Returns
     -------
     dict
         Array elements.
     """
-    with open(files("simtools") / "schemas/array_elements.yml", encoding="utf-8") as file:
+    with open(Path(SCHEMA_PATH) / "array_elements.yml", encoding="utf-8") as file:
         return yaml.safe_load(file)["data"]
 
 
 @cache
 def site_names():
     """
-    Site names from reference file.
+    Get site names.
 
-    The list of sites is derived from the sites listed in the model parameter
-    schema files. Return a dictionary for compatibility with the validation routines.
+    The list of sites is derived from the sites listed in array element definition file.
+    Return a dictionary for compatibility with the validation '_validate_name' routine.
 
     Returns
     -------
     dict
         Site names.
     """
-    _array_elements = array_elements()
-    _sites = {entry["site"] for entry in _array_elements.values()}
-    return {site: [site.lower()] for site in _sites}
+    return {
+        site: [site.lower()]
+        for entry in array_elements().values()
+        for site in (entry["site"] if isinstance(entry["site"], list) else [entry["site"]])
+    }
 
 
 @cache
-def load_model_parameters(class_key_list):
-    model_parameters = {}
-    schema_files = list(Path(files("simtools") / "schemas/model_parameters").rglob("*.yml"))
-    for schema_file in schema_files:
+def array_element_design_types(array_element_type):
+    """
+    Get array element site types (e.g., 'design' or 'flashcam').
+
+    Default values are ['design', 'test'].
+
+    Parameters
+    ----------
+    array_element_type
+        Array element type
+
+    Returns
+    -------
+    list
+        Array element design types.
+    """
+    default_types = ["design", "test"]
+    if array_element_type is None:
+        return default_types
+    try:
+        return array_elements()[array_element_type].get("design_types", default_types)
+    except KeyError as exc:
+        raise ValueError(f"Invalid name {array_element_type}") from exc
+
+
+def is_design_type(array_element_name):
+    """
+    Check if array element is a design type (e.g., "MSTS-FlashCam" or "LSTN-design").
+
+    Parameters
+    ----------
+    array_element_name: str
+        Array element name.
+
+    Returns
+    -------
+    bool
+        True if array element is a design type.
+    """
+    return get_array_element_id_from_name(array_element_name) in array_element_design_types(
+        get_array_element_type_from_name(array_element_name)
+    )
+
+
+@cache
+def _load_model_parameters():
+    """
+    Get model parameters properties from schema files.
+
+    Returns
+    -------
+    dict
+        Model parameters definitions for all model parameters.
+    """
+    _parameters = {}
+    for schema_file in list(Path(MODEL_PARAMETER_SCHEMA_PATH).rglob("*.yml")):
         with open(schema_file, encoding="utf-8") as f:
             data = yaml.safe_load(f)
-        try:
-            if data["instrument"]["class"] in class_key_list:
-                model_parameters[data["name"]] = data
-        except KeyError:
-            pass
-    return model_parameters
+            _parameters[data["name"]] = data
+    return _parameters
+
+
+def model_parameters(class_key_list=None):
+    """
+    Get model parameters and their properties for a given instrument class key.
+
+    Returns all model parameters if class_key is None.
+
+    Parameters
+    ----------
+    class_key: str, None
+        Class key (e.g., "telescope", "camera", structure").
+
+    Returns
+    -------
+    dict
+        Model parameters definitions.
+    """
+    _parameters = {}
+    if class_key_list is None:
+        return _load_model_parameters()
+    for key, value in _load_model_parameters().items():
+        if value.get("instrument", {}).get("class", "") in class_key_list:
+            _parameters[key] = value
+    return _parameters
 
 
 def site_parameters():
-    return load_model_parameters(class_key_list="Site")
+    """Return site model parameters."""
+    return model_parameters(class_key_list=tuple(db_collections_to_class_keys["sites"]))
 
 
 def telescope_parameters():
-    return load_model_parameters(class_key_list=("Structure", "Camera", "Telescope"))
+    """Return telescope model parameters."""
+    return model_parameters(class_key_list=tuple(db_collections_to_class_keys["telescopes"]))
+
 
+def instrument_class_key_to_db_collection(class_name):
+    """Convert instrument class key to collection name."""
+    for collection, classes in db_collections_to_class_keys.items():
+        if class_name in classes:
+            return collection
+    raise ValueError(f"Class {class_name} not found")
 
-def validate_array_element_id_name(name):
+
+def db_collection_to_instrument_class_key(collection_name="telescopes"):
+    """Return list of instrument classes for a given collection."""
+    try:
+        return db_collections_to_class_keys[collection_name]
+    except KeyError as exc:
+        raise KeyError(f"Invalid collection name {collection_name}") from exc
+
+
+def validate_array_element_id_name(array_element_id, array_element_type=None):
     """
     Validate array element ID.
 
     Allowed IDs are
-    - design (for design array elements or testing)
+    - design types (for design array elements or testing)
     - array element ID (e.g., 1, 5, 15)
     - test (for testing)
 
@@ -92,6 +206,8 @@ def validate_array_element_id_name(name):
     ----------
     name: str or int
         Array element ID name.
+    array_element_type: str
+        Array element type (e.g., LSTN, MSTN).
 
     Returns
     -------
@@ -103,23 +219,20 @@ def validate_array_element_id_name(name):
     ValueError
         If name is not valid.
     """
-    if isinstance(name, int) or name.isdigit():
-        return f"{int(name):02d}"
-    if name.lower() in ("design", "test"):
-        return str(name).lower()
+    if isinstance(array_element_id, int) or array_element_id.isdigit():
+        return f"{int(array_element_id):02d}"
+    if array_element_id in array_element_design_types(array_element_type):
+        return str(array_element_id)
+    raise ValueError(f"Invalid array element ID name {array_element_id}")
 
-    msg = f"Invalid array element ID name {name}"
-    _logger.error(msg)
-    raise ValueError(msg)
 
-
-def validate_site_name(name):
+def validate_site_name(site_name):
     """
     Validate site name.
 
     Parameters
     ----------
-    name: str
+    site_name: str
         Site name.
 
     Returns
@@ -127,7 +240,7 @@ def validate_site_name(name):
     str
         Validated name.
     """
-    return _validate_name(name, site_names())
+    return _validate_name(site_name, site_names())
 
 
 def _validate_name(name, all_names):
@@ -166,13 +279,13 @@ def _validate_name(name, all_names):
     raise ValueError(msg)
 
 
-def validate_array_element_type(name):
+def validate_array_element_type(array_element_type):
     """
     Validate array element type (e.g., LSTN, MSTN).
 
     Parameters
     ----------
-    name: str
+    array_element_type: str
         Array element type.
 
     Returns
@@ -180,16 +293,18 @@ def validate_array_element_type(name):
     str
         Validated name.
     """
-    return _validate_name(name, array_elements())
+    return _validate_name(array_element_type, array_elements())
 
 
-def validate_array_element_name(name):
+def validate_array_element_name(array_element_name):
     """
-    Validate array element name (e.g., MSTN-design, MSTN-01).
+    Validate array element name (e.g., MSTx-NectarCam, MSTN-01).
+
+    Forgiving validation, is it allows also to give a site name (e.g., OBS-North).
 
     Parameters
     ----------
-    name: str
+    array_element_name: str
         Array element name.
 
     Returns
@@ -198,20 +313,22 @@ def validate_array_element_name(name):
         Validated name.
     """
     try:
-        _array_element_type, _array_element_id = name.split("-")
+        _array_element_type, _array_element_id = array_element_name.split("-")
     except ValueError as exc:
-        msg = f"Invalid name {name}"
+        msg = f"Invalid name {array_element_name}"
         raise ValueError(msg) from exc
+    if _array_element_type == "OBS":
+        return validate_site_name(_array_element_id)
     return (
         _validate_name(_array_element_type, array_elements())
         + "-"
-        + validate_array_element_id_name(_array_element_id)
+        + validate_array_element_id_name(_array_element_id, _array_element_type)
     )
 
 
-def get_array_element_name_from_type_site_id(array_element_type, site, array_element_id):
+def generate_array_element_name_from_type_site_id(array_element_type, site, array_element_id):
     """
-    Get array element name from type, site and ID.
+    Generate a new array element name from array element type, site, and array element ID.
 
     Parameters
     ----------
@@ -228,17 +345,17 @@ def get_array_element_name_from_type_site_id(array_element_type, site, array_ele
         Array element name.
     """
     _short_site = validate_site_name(site)[0]
-    _val_id = validate_array_element_id_name(array_element_id)
+    _val_id = validate_array_element_id_name(array_element_id, array_element_type)
     return f"{array_element_type}{_short_site}-{_val_id}"
 
 
-def get_array_element_type_from_name(name):
+def get_array_element_type_from_name(array_element_name):
     """
-    Get array element type from name, e.g. "LSTN", "MSTN".
+    Get array element type from array element name (e.g "MSTN" from "MSTN-01").
 
     Parameters
     ----------
-    name: str
+    array_element_name: str
         Array element name
 
     Returns
@@ -246,14 +363,36 @@ def get_array_element_type_from_name(name):
     str
         Array element type.
     """
-    return _validate_name(name.split("-")[0], array_elements())
+    return _validate_name(array_element_name.split("-")[0], array_elements())
+
+
+def get_array_element_id_from_name(array_element_name):
+    """
+    Get array element ID from array element name, (e.g. "01" from "MSTN-01").
+
+    Parameters
+    ----------
+    array_element_name: str
+        Array element name
+
+    Returns
+    -------
+    str
+        Array element ID.
+    """
+    try:
+        return validate_array_element_id_name(
+            array_element_name.split("-")[1], array_element_name.split("-")[0]
+        )
+    except IndexError as exc:
+        raise ValueError(f"Invalid name {array_element_name}") from exc
 
 
 def get_list_of_array_element_types(
     array_element_class="telescopes", site=None, observatory="CTAO"
 ):
     """
-    Get list of array element types.
+    Get list of array element types (e.g., ["LSTN", "MSTN"] for the Northern site).
 
     Parameters
     ----------
@@ -267,135 +406,136 @@ def get_list_of_array_element_types(
     list
         List of array element types.
     """
-    return [
-        key
-        for key, value in array_elements().items()
-        if value["collection"] == array_element_class
-        and (site is None or value["site"] == site)
-        and (observatory is None or value["observatory"] == observatory)
-    ]
+    return sorted(
+        [
+            key
+            for key, value in array_elements().items()
+            if value["collection"] == array_element_class
+            and (site is None or value["site"] == site)
+            and (observatory is None or value["observatory"] == observatory)
+        ]
+    )
 
 
-def get_site_from_array_element_name(name):
+def get_site_from_array_element_name(array_element_name):
     """
-    Get site name from array element name.
+    Get site name from array element name (e.g., "South" from "MSTS-01").
 
     Parameters
     ----------
-    name: str
+    array_element_name: str
         Array element name.
 
     Returns
     -------
-    str
-        Site name (South or North).
+    str, list
+        Site name(s).
     """
-    return array_elements()[get_array_element_type_from_name(name)]["site"]
+    try:  # e.g. instrument is 'North' as given for the site parameters
+        return validate_site_name(array_element_name)
+    except ValueError:  # e.g. instrument is 'LSTN' as given for the array element types
+        return array_elements()[get_array_element_type_from_name(array_element_name)]["site"]
 
 
-def get_collection_name_from_array_element_name(name):
+def get_collection_name_from_array_element_name(array_element_name, array_elements_only=True):
     """
-    Get collection name (e.g., telescopes, calibration_devices, sites) of array element from name.
+    Get collection name (e.g., telescopes, calibration_devices) of an array element from its name.
 
     Parameters
     ----------
-    name: str
-        Array element name.
+    array_element_name: str
+        Array element name (e.g. LSTN-01)
+    array_elements_only: bool
+        If True, only array elements are considered (e.g. "OBS-North" will raise a ValueError).
 
     Returns
     -------
     str
         Collection name .
+
+    Raises
+    ------
+    ValueError
+        If name is not a valid array element name.
     """
     try:
-        return array_elements()[get_array_element_type_from_name(name)]["collection"]
+        return array_elements()[get_array_element_type_from_name(array_element_name)]["collection"]
+    except ValueError as exc:
+        if array_elements_only:
+            raise ValueError(f"Invalid array element name {array_element_name}") from exc
+    try:
+        if array_element_name.startswith("OBS") or validate_site_name(array_element_name):
+            return "sites"
     except ValueError:
         pass
-    try:
-        validate_site_name(name)
-        return "sites"
-    except ValueError as exc:
-        raise ValueError(f"Invalid array element name {name}: {exc}") from exc
+    if array_element_name in {
+        "configuration_sim_telarray",
+        "configuration_corsika",
+        "Files",
+        "Dummy-Telescope",
+    }:
+        return array_element_name
+    raise ValueError(f"Invalid array element name {array_element_name}")
 
 
-def get_simulation_software_name_from_parameter_name(
-    par_name,
-    simulation_software="sim_telarray",
-    search_telescope_parameters=True,
-    search_site_parameters=True,
-):
+def get_collection_name_from_parameter_name(parameter_name):
     """
-    Get the name used in the simulation software from the model parameter name.
-
-    Name convention is expected to be defined in the schema.
-    Returns the parameter name if no simulation software name is found.
+    Get the db collection name for a given parameter.
 
     Parameters
     ----------
-    par_name: str
-        Model parameter name.
-    simulation_software: str
-        Simulation software name.
-    search_telescope_parameters: bool
-        If True, telescope model parameters are included.
-    search_site_parameters: bool
-        If True, site model parameters are included.
+    parameter_name: str
+        Name of the parameter.
 
     Returns
     -------
     str
-        Simtel parameter name.
-    """
-    _parameter_names = {}
-    if search_telescope_parameters:
-        _parameter_names.update(telescope_parameters())
-    if search_site_parameters:
-        _parameter_names.update(site_parameters())
-
-    try:
-        _parameter = _parameter_names[par_name]
-    except KeyError as err:
-        _logger.error(f"Parameter {par_name} without schema definition")
-        raise err
+        Collection name.
 
+    Raises
+    ------
+    KeyError
+        If the parameter name is not found in the list of model parameters
+    """
+    _parameter_names = model_parameters()
     try:
-        for software in _parameter.get("simulation_software", []):
-            if software.get("name") == simulation_software:
-                return software.get("internal_parameter_name", par_name)
-    except TypeError:  # catches cases for which 'simulation_software' is None
-        pass
-    return None
+        class_key = _parameter_names[parameter_name].get("instrument", {}).get("class")
+    except KeyError as exc:
+        raise KeyError(f"Parameter {parameter_name} without schema definition") from exc
+    return instrument_class_key_to_db_collection(class_key)
 
 
-def get_parameter_name_from_simtel_name(simtel_name):
+def get_simulation_software_name_from_parameter_name(
+    parameter_name,
+    simulation_software="sim_telarray",
+):
     """
-    Get the model parameter name from the simtel parameter name.
+    Get the name used in the given simulation software from the model parameter name.
 
-    Assumes that both names are equal if not defined otherwise in names.py.
+    Name convention is expected to be defined in the model parameter schema.
+    Returns the parameter name if no simulation software name is found.
 
     Parameters
     ----------
-    simtel_name: str
-        Simtel parameter name.
+    parameter_name: str
+        Model parameter name.
+    simulation_software: str
+        Simulation software name.
 
     Returns
     -------
     str
-        Model parameter name.
+        Simtel parameter name.
     """
-    _parameters = {**telescope_parameters(), **site_parameters()}
+    _parameter = model_parameters().get(parameter_name)
+    if not _parameter:
+        raise KeyError(f"Parameter {parameter_name} without schema definition")
+
+    for software in _parameter.get("simulation_software", []):
+        if software.get("name") == simulation_software:
+            return software.get("internal_parameter_name", parameter_name)
 
-    for par_name, par_info in _parameters.items():
-        try:
-            for software in par_info["simulation_software"]:
-                if (
-                    software["name"] == "sim_telarray"
-                    and software["internal_parameter_name"] == simtel_name
-                ):
-                    return par_name
-        except (KeyError, TypeError):  # catches cases for which 'simulation_software' is None
-            pass
-    return simtel_name
+    return None
 
 
 def simtel_config_file_name(
@@ -469,28 +609,6 @@ def simtel_single_mirror_list_file_name(
     return name
 
 
-def layout_telescope_list_file_name(name, label):
-    """
-    File name for files required at the RayTracing class.
-
-    Parameters
-    ----------
-    name: str
-        Name of the array.
-    label: str
-        Instance label.
-
-    Returns
-    -------
-    str
-        File name.
-    """
-    file_name = f"telescope_positions-{name}"
-    file_name += f"_{label}" if label is not None else ""
-    file_name += ".ecsv"
-    return file_name
-
-
 def generate_file_name(
     file_type,
     suffix,
@@ -575,12 +693,10 @@ def sanitize_name(name):
     ValueError:
         if the string name can not be sanitized.
     """
-    # Convert to lowercase
+    if name is None:
+        return None
     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():
@@ -588,3 +704,29 @@ def sanitize_name(name):
         _logger.error(msg)
         raise ValueError(msg)
     return sanitized
+
+
+def file_name_with_version(file_name, suffix):
+    """
+    Return a file name including a semantic version with the correct suffix.
+
+    Replaces 'Path.suffix()', which removes trailing numbers (and therefore version numbers).
+
+    Parameters
+    ----------
+    file_name: str
+        File name.
+    suffix: str
+        File suffix.
+
+    Returns
+    -------
+    Path
+        File name with version number.
+    """
+    if file_name is None or suffix is None:
+        return None
+    file_name = str(file_name)
+    if bool(re.search(r"\d+\.\d+\.\d+$", file_name)):
+        return Path(file_name + suffix)
+    return Path(file_name).with_suffix(suffix)