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

simtools/applications/db_get_parameter_from_db.py

@@ -26,7 +26,7 @@ r"""
 
     Example
     -------
-    Get the mirror_list parameter from the DB.
+    Get the mirror_list parameter used for a given model_version from the DB.
 
     .. code-block:: console
 
@@ -34,18 +34,13 @@ r"""
                 --site North --telescope LSTN-01 \\
                 --model_version 5.0.0
 
-    Expected final print-out message:
+    Get the mirror_list parameter using the parameter_version from the DB.
 
     .. code-block:: console
 
-        {'Applicable': True,
-         'File': True,
-         'Type': 'str',
-         'Value': 'mirror_CTA-N-LST1_v2019-03-31.dat',
-         'Version': '5.0.0',
-         '_id': ObjectId('608834f257df2db2531b8e78'),
-         'entry_date': datetime.datetime(2021, 4, 27, 15, 59, 46, tzinfo=<bson.tz_util.FixedOffset \
-          object at 0x7f601dd51d80>)}
+        simtools-db-get-parameter-from-db --parameter mirror_list \\
+                --site North --telescope LSTN-01 \\
+                --parameter_version 1.0.0
 
 """
 
@@ -58,6 +53,7 @@ import simtools.utils.general as gen
 from simtools.configuration import configurator
 from simtools.db import db_handler
 from simtools.io_operations import io_handler
+from simtools.utils import names
 
 
 def _parse():
@@ -70,12 +66,6 @@ def _parse():
     )
 
     config.parser.add_argument("--parameter", help="Parameter name", type=str, required=True)
-    config.parser.add_argument(
-        "--db_collection",
-        help="DB collection to which to add the file",
-        default="telescopes",
-        required=False,
-    )
     config.parser.add_argument(
         "--output_file",
         help="output file name (if not given: print to stdout)",
@@ -83,7 +73,9 @@ def _parse():
         required=False,
     )
 
-    return config.initialize(db_config=True, simulation_model=["telescope", "model_version"])
+    return config.initialize(
+        db_config=True, simulation_model=["telescope", "parameter_version", "model_version"]
+    )
 
 
 def main():  # noqa: D103
@@ -94,37 +86,36 @@ def main():  # noqa: D103
 
     db = db_handler.DatabaseHandler(mongo_db_config=db_config)
 
-    if args_dict["db_collection"] == "configuration_sim_telarray":
-        pars = db.get_model_parameters(
-            args_dict["site"],
-            args_dict["telescope"],
-            args_dict["model_version"],
-            collection="configuration_sim_telarray",
+    # get parameter using 'parameter_version'
+    if args_dict["parameter_version"] is not None:
+        pars = db.get_model_parameter(
+            parameter=args_dict["parameter"],
+            parameter_version=args_dict["parameter_version"],
+            site=args_dict["site"],
+            array_element_name=args_dict["telescope"],
         )
-    elif args_dict["db_collection"] == "configuration_corsika":
-        pars = db.get_corsika_configuration_parameters(args_dict["model_version"])
-    elif args_dict["telescope"] is not None:
+    # get parameter using 'model_version'
+    elif args_dict["model_version"] is not None:
         pars = db.get_model_parameters(
-            args_dict["site"],
-            args_dict["telescope"],
-            args_dict["model_version"],
-            collection="telescopes",
+            site=args_dict["site"],
+            array_element_name=args_dict.get("telescope"),
+            model_version=args_dict["model_version"],
+            collection=names.get_collection_name_from_parameter_name(args_dict["parameter"]),
         )
     else:
-        pars = db.get_site_parameters(args_dict["site"], args_dict["model_version"])
+        raise ValueError("Either 'parameter_version' or 'model_version' must be provided.")
     if args_dict["parameter"] not in pars:
         raise KeyError(f"The requested parameter, {args_dict['parameter']}, does not exist.")
     if args_dict["output_file"] is not None:
-        _io_handler = io_handler.IOHandler()
+        _output_file = (
+            Path(io_handler.IOHandler().get_output_directory()) / args_dict["output_file"]
+        )
         pars[args_dict["parameter"]].pop("_id")
         pars[args_dict["parameter"]].pop("entry_date")
-        _output_file = Path(_io_handler.get_output_directory()) / args_dict["output_file"]
         with open(_output_file, "w", encoding="utf-8") as json_file:
             json.dump(pars[args_dict["parameter"]], json_file, indent=4)
     else:
-        print()
         pprint(pars[args_dict["parameter"]])
-        print()
 
 
 if __name__ == "__main__":

simtools/applications/derive_mirror_rnda.py

@@ -194,8 +194,7 @@ def _parse(label):
     config.parser.add_argument(
         "--random_focal_length",
         help=(
-            "Value of the random focal length. "
-            "Only used if 'use_random_focal_length' is activated."
+            "Value of the random focal length. Only used if 'use_random_focal_length' is activated."
         ),
         default=None,
         type=float,

simtools/applications/derive_photon_electron_spectrum.py

@@ -0,0 +1,99 @@
+#!/usr/bin/python3
+
+r"""
+    Derive single photon electron spectrum from a given amplitude spectrum.
+
+    Normalizes singe-p.e. amplitude distribution to mean amplitude of 1.0,
+    as required by sim_telarray. Allows to fold in afterpulse distribution
+    to prompt a spectrum. Uses the sim_telarray tool 'norm_spe' to normalize
+    the spectra.
+
+    Input files can be in ecsv format (preferred) or in the sim_telarray legacy format.
+
+    Two output files with identical data are written to the output directory:
+
+    - 'output_file'.ecsv: Single photon electron spectrum in ecsv format (data and metadata).
+    - 'output_file'.dat: Single photon electron spectrum in sim_telarray format.
+
+    Example
+    -------
+
+    .. code-block:: console
+
+        simtools-derive-photon-electron-spectrum \\
+            --input_spectrum spectrum_photon_electron.ecsv \\
+            --afterpulse_spectrum spectrum_afterpulse.ecsv \\
+            --step_size 0.02 \\
+            --max_amplitude 42.0 \\
+            --use_norm_spe \\
+            --output_path ./tests/output \\
+            --output_file spectrum_photon_electron_afterpulse.ecsv
+
+    For an example of how to plot the single photon electron spectrum, see the
+    integration test 'tests/integration_tests/config/plot_tabular_data_for_single_pe_data.yml'.
+
+"""
+
+import logging
+from pathlib import Path
+
+import simtools.utils.general as gen
+from simtools.camera.single_photon_electron_spectrum import SinglePhotonElectronSpectrum
+from simtools.configuration import configurator
+
+
+def _parse(label):
+    """Parse command line configuration."""
+    config = configurator.Configurator(
+        label=label,
+        description="Derive single photon electron spectrum from a given amplitude spectrum.",
+    )
+    config.parser.add_argument(
+        "--input_spectrum",
+        help="File with amplitude spectrum.",
+        type=Path,
+        required=True,
+    )
+    config.parser.add_argument(
+        "--afterpulse_spectrum",
+        help="File with afterpulse spectrum.",
+        type=Path,
+        required=False,
+    )
+    config.parser.add_argument(
+        "--step_size",
+        help="Step size in amplitude spectrum",
+        type=float,
+        default=0.02,
+        required=False,
+    )
+    config.parser.add_argument(
+        "--max_amplitude",
+        help="Maximum amplitude in amplitude spectrum",
+        type=float,
+        default=42.0,
+        required=False,
+    )
+    config.parser.add_argument(
+        "--use_norm_spe",
+        help="Use sim_telarray tool 'norm_spe' to normalize the spectrum.",
+        action="store_true",
+        required=False,
+    )
+
+    return config.initialize(db_config=False, output=True)
+
+
+def main():  # noqa: D103
+    args_dict, _ = _parse(Path(__file__).stem)
+
+    logger = logging.getLogger()
+    logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
+
+    single_pe = SinglePhotonElectronSpectrum(args_dict)
+    single_pe.derive_single_pe_spectrum()
+    single_pe.write_single_pe_spectrum()
+
+
+if __name__ == "__main__":
+    main()

simtools/applications/derive_psf_parameters.py

@@ -81,6 +81,7 @@ r"""
         mirror_align_random_vertical = [0.005, 28.0, 0.0, 0.0]
 
 """
+
 import logging
 from collections import OrderedDict
 

simtools/applications/docs_produce_array_element_report.py

@@ -0,0 +1,71 @@
+#!/usr/bin/python3
+
+r"""
+Produces a markdown file for a given array element, site, and model version.
+
+The report includes detailed information on each parameter,
+such as the parameter name, value, unit, description, and short description.
+Currently only implemented for telescopes.
+"""
+
+import logging
+
+from simtools.configuration import configurator
+from simtools.io_operations import io_handler
+from simtools.model.telescope_model import TelescopeModel
+from simtools.reporting.docs_read_parameters import ReadParameters
+from simtools.utils import general as gen
+
+
+def _parse(label):
+    """Parse command line configuration."""
+    config = configurator.Configurator(
+        label=label,
+        description=("Produce a markdown report for model parameters."),
+    )
+
+    config.parser.add_argument(
+        "--parameter",
+        action="store_true",
+        help="Compare all parameters across model versions for one telescope.",
+    )
+
+    return config.initialize(
+        db_config=True, simulation_model=["site", "telescope", "model_version", "parameter_version"]
+    )
+
+
+def main():  # noqa: D103
+    label_name = "reports"
+    args, db_config = _parse(label_name)
+    io_handler_instance = io_handler.IOHandler()
+    output_path = io_handler_instance.get_output_directory(
+        label=label_name, sub_dir=f"productions/{args['model_version']}"
+    )
+
+    logger = logging.getLogger()
+    logger.setLevel(gen.get_log_level_from_user(args["log_level"]))
+
+    telescope_model = TelescopeModel(
+        site=args["site"],
+        telescope_name=args["telescope"],
+        model_version=args["model_version"],
+        label=label_name,
+        mongo_db_config=db_config,
+    )
+
+    ReadParameters(
+        db_config,
+        telescope_model,
+        output_path,
+    ).produce_array_element_report()
+
+    logger.info(
+        f"Markdown report generated for {args['site']}"
+        f" Telescope {args['telescope']} (v{args['model_version']}):"
+        f" {output_path}"
+    )
+
+
+if __name__ == "__main__":
+    main()

simtools/applications/docs_produce_model_parameter_reports.py

@@ -0,0 +1,63 @@
+#!/usr/bin/python3
+
+r"""
+Produce one file per model parameter for a given array element.
+
+The markdown reports include detailed information on each parameter,
+comparing their values over various model versions.
+Currently only implemented for telescopes.
+"""
+
+import logging
+
+from simtools.configuration import configurator
+from simtools.io_operations import io_handler
+from simtools.model.telescope_model import TelescopeModel
+from simtools.reporting.docs_read_parameters import ReadParameters
+from simtools.utils import general as gen
+
+
+def _parse(label):
+    """Parse command line configuration."""
+    config = configurator.Configurator(
+        label=label,
+        description=("Produce a markdown report for model parameters."),
+    )
+
+    return config.initialize(
+        db_config=True, simulation_model=["site", "telescope", "model_version"]
+    )
+
+
+def main():  # noqa: D103
+    label_name = "reports"
+    args, db_config = _parse(label_name)
+    io_handler_instance = io_handler.IOHandler()
+    output_path = io_handler_instance.get_output_directory(label=label_name, sub_dir="parameters")
+
+    logger = logging.getLogger()
+    logger.setLevel(gen.get_log_level_from_user(args["log_level"]))
+
+    telescope_model = TelescopeModel(
+        site=args["site"],
+        telescope_name=args["telescope"],
+        model_version=args["model_version"],
+        label=label_name,
+        mongo_db_config=db_config,
+    )
+
+    ReadParameters(
+        db_config,
+        telescope_model,
+        output_path,
+    ).produce_model_parameter_reports()
+
+    logger.info(
+        f"Markdown report generated for {args['site']}"
+        f" Telescope {args['telescope']} (v{args['model_version']}):"
+        f" {output_path}"
+    )
+
+
+if __name__ == "__main__":
+    main()

simtools/applications/generate_array_config.py

@@ -1,28 +1,28 @@
 #!/usr/bin/python3
 """
-    Generate sim_telarray configuration files for a given array.
+Generate sim_telarray configuration files for a given array.
 
-    The applications generates the sim_telarray configuration files for a given array, site,
-    and model_version using the model parameters stored in the database.
+The applications generates the sim_telarray configuration files for a given array, site,
+and model_version using the model parameters stored in the database.
 
-    Command line arguments
-    ----------------------
-    site : str
-        Site name (e.g., North, South).
-    array_layout_name : str
-        Name of the layout array (e.g., test_layout, alpha, 4mst, etc.).
-    array_element_list : list
-        List of array elements (e.g., telescopes) to plot (e.g., ``LSTN-01 LSTN-02 MSTN``).
+Command line arguments
+----------------------
+site : str
+    Site name (e.g., North, South).
+array_layout_name : str
+    Name of the layout array (e.g., test_layout, alpha, 4mst, etc.).
+array_element_list : list
+    List of array elements (e.g., telescopes) to plot (e.g., ``LSTN-01 LSTN-02 MSTN``).
 
-    Example
-    -------
-    North - 5.0.0:
+Example
+-------
+North - 5.0.0:
 
-    .. code-block:: console
+.. code-block:: console
 
-        simtools-generate-array-config --site North --array_layout_name alpha --model_version 5.0.0
+    simtools-generate-array-config --site North --array_layout_name alpha --model_version 5.0.0
 
-    The output is saved in simtools-output/test/model.
+The output is saved in simtools-output/test/model.
 """
 
 import logging

simtools/applications/generate_corsika_histograms.py

@@ -152,7 +152,7 @@ r"""
      .. code-block:: console
 
         simtools-generate-corsika-histograms --iact_file /workdir/external/simtools/\\
-        testsresources/tel_output_10GeV-2-gamma-20deg-CTAO-South.corsikaio \\
+        tests/resources/tel_output_10GeV-2-gamma-20deg-CTAO-South.corsikaio \\
             --pdf --hdf5 \\
             --event_2d_histograms zenith azimuth --event_1d_histograms total_energy
 
@@ -208,7 +208,7 @@ def _parse(label, description):
 
     config.parser.add_argument(
         "--telescope_indices",
-        help="Name of the CORSIKA IACT file from which to generate the histograms.",
+        help="List of telescope indices to be considered in the generation of the histograms",
         type=str,
         required=False,
         nargs="+",

simtools/applications/generate_regular_arrays.py

@@ -1,27 +1,27 @@
 #!/usr/bin/python3
 
 """
-    Make a regular array of telescopes and save it as astropy table.
+Make a regular array of telescopes and save it as astropy table.
 
-    The arrays consist of one telescope at the center of the array and or of 4 telescopes
-    in a square grid. These arrays are used for trigger rate simulations.
+The arrays consist of one telescope at the center of the array and or of 4 telescopes
+in a square grid. These arrays are used for trigger rate simulations.
 
-    The array layout files created will be available at the data/layout directory.
+The array layout files created will be available at the data/layout directory.
 
-    Command line arguments
-    ----------------------
-    site (str, required)
-        observatory site (e.g., North or South).
-    model_version (str, optional)
-        Model version to use (e.g., 6.0.0). If not provided, the latest version is used.
+Command line arguments
+----------------------
+site (str, required)
+    observatory site (e.g., North or South).
+model_version (str, optional)
+    Model version to use (e.g., 6.0.0). If not provided, the latest version is used.
 
-    Example
-    -------
-    Runtime < 10 s.
+Example
+-------
+Runtime < 10 s.
 
-    .. code-block:: console
+.. code-block:: console
 
-        simtools-generate-regular-arrays --site=North
+    simtools-generate-regular-arrays --site=North
 """
 
 import logging
@@ -77,7 +77,9 @@ def main():
         # Single telescope at the center
         if array_name[0] == "1":
             tel_name.append(
-                names.get_array_element_name_from_type_site_id(tel_size, args_dict["site"], "01")
+                names.generate_array_element_name_from_type_site_id(
+                    tel_size, args_dict["site"], "01"
+                )
             )
             pos_x.append(0 * u.m)
             pos_y.append(0 * u.m)
@@ -86,7 +88,7 @@ def main():
         else:
             for i in range(1, 5):
                 tel_name.append(
-                    names.get_array_element_name_from_type_site_id(
+                    names.generate_array_element_name_from_type_site_id(
                         tel_size, args_dict["site"], f"0{i}"
                     )
                 )

simtools/applications/generate_simtel_array_histograms.py

@@ -13,8 +13,6 @@ r"""
         Name of the histogram files to be plotted.
         It can be given as the histogram file names (more than one option allowed) or as a text
         file with the names of the histogram files in it.
-    figure_name (str, required)
-        File name for the pdf output (without extension).
     pdf (bool, optional)
         If set, histograms are saved into pdf files.
         One pdf file contains all the histograms found in the file.
@@ -29,6 +27,8 @@ r"""
         If the output output_file_name.hdf5 file already exists and hdf5 is set, the tables
         associated to hdf5 will be overwritten. The remaining tables, if any, will stay
         untouched.
+    test: bool
+        Test option. Generate only two histograms for testing purposes.
 
     Raises
     ------
@@ -108,38 +108,6 @@ def _parse(label, description):
     return config_parser
 
 
-def build_histogram_files(config_parser, logger):
-    """
-    Build a list of histogram files from command line arguments.
-
-    Parameters
-    ----------
-    config_parser: dict
-        Parsed command line arguments.
-    logger: logging.Logger
-        Logger object for logging messages.
-
-    Returns
-    -------
-    list
-        List of histogram file paths.
-    """
-    histogram_files = []
-    for one_file in config_parser["hist_file_names"]:
-        try:
-            if Path(one_file).suffix in [".zst", ".simtel", ".hdata"]:
-                histogram_files.append(one_file)
-            else:
-                with open(one_file, encoding="utf-8") as file:
-                    for line in file:
-                        histogram_files.append(line.strip())
-        except FileNotFoundError as exc:
-            msg = f"{one_file} is not a file."
-            logger.error(msg)
-            raise FileNotFoundError from exc
-    return histogram_files
-
-
 def check_and_log_overwrite(config_parser, logger):
     """
     Check if the output hdf5 file already exists and log a warning if it does.
@@ -197,36 +165,31 @@ def create_pdf(simtel_histograms, output_file_name, config_parser, logger):
         logger.info(f"Wrote histograms to the pdf file {output_file_name}.pdf")
 
 
-def export_to_hdf5(simtel_histograms, output_file_name, overwrite, config_parser, logger):
-    """Export histograms to an HDF5 file."""
-    if config_parser["hdf5"]:
-        logger.info(f"Wrote histograms to the hdf5 file {output_file_name}.hdf5")
-        simtel_histograms.export_histograms(f"{output_file_name}.hdf5", overwrite=overwrite)
-
-
 def main():  # noqa: D103
     label = Path(__file__).stem
-    description = "Display the simtel_array histograms."
+    description = "Display simtel_array histograms and/or write them into hdf5 format."
     io_handler_instance = io_handler.IOHandler()
     config_parser = _parse(label, description)
     output_path = io_handler_instance.get_output_directory(label, sub_dir="application-plots")
     logger = logging.getLogger()
     logger.setLevel(gen.get_log_level_from_user(config_parser["log_level"]))
-    logger.info("Starting the application.")
 
-    histogram_files = build_histogram_files(config_parser, logger)
+    histogram_files = gen.get_list_of_files_from_command_line(
+        config_parser["hist_file_names"], [".zst", ".simtel", ".hdata"]
+    )
 
     # If no output name is passed, the tool gets the name of the first histogram of the list
     if config_parser["output_file_name"] is None:
         config_parser["output_file_name"] = Path(histogram_files[0]).absolute().name
     output_file_name = Path(output_path).joinpath(f"{config_parser['output_file_name']}")
 
-    # If the hdf5 output file already exists, it is overwritten
-    overwrite = check_and_log_overwrite(config_parser, logger)
-
     simtel_histograms = SimtelIOHistograms(histogram_files)
     create_pdf(simtel_histograms, output_file_name, config_parser, logger)
-    export_to_hdf5(simtel_histograms, output_file_name, overwrite, config_parser, logger)
+    if config_parser["hdf5"]:
+        simtel_histograms.export_histograms(
+            f"{output_file_name}.hdf5",
+            overwrite=check_and_log_overwrite(config_parser, logger),
+        )
 
 
 if __name__ == "__main__":