gammasimtools 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

simtools/applications/generate_corsika_histograms.py

@@ -1,174 +1,78 @@
 #!/usr/bin/python3
 
 r"""
-    Generates a set of histograms Cherenkov photon distributions from CORSIKA output.
+    Generates a set of histograms with Cherenkov photon distributions from CORSIKA output.
 
     The Cherenkov photons (from observation level) are read from a CORSIKA IACT
-    output file provided as input.
-
-    The histograms can be saved both into pdfs and in a hdf5 file.
+    output file(s) provided as input.
 
     The following 2D histograms are generated:
-        - Number of Cherenkov photons on the ground;
-        - Density of Cherenkov photons on the ground;
-        - Incoming direction (directive cosines) of the Cherenkov photons;
-        - Time of arrival (ns) vs altitude of production (km);
-        - Number of Cherenkov photons per event per telescope.
+
+        - Density of Cherenkov photons on the ground
+        - Incoming direction (directive cosines) of the Cherenkov photons
+        - Time of arrival (ns) vs altitude of production (km)
 
     The following 1D histograms are generated:
-        - Wavelength;
-        - Counts;
-        - Density;
-        - Time of arrival;
-        - Altitude of production;
-        - Number of photons per telescope;
-        - Number of photons per event.
 
-    Histograms for the distribution of CORSIKA event header elements can also be generated by using
-    the --event_1d_histograms and --event_2d_histograms arguments. The accepted arguments (keys)
-    are to be found in the CORSIKA manual, e.g., "total_energy", "zenith", "azimuth".
+        - Wavelength distribution of Cherenkov photons
+        - Time of arrival (ns) distribution of Cherenkov photons
+        - Altitude of production (km) distribution of Cherenkov photons
+        - Lateral distribution of Cherenkov photons (distance from shower core in m)
 
     Command line arguments
     ----------------------
-    iact_file (str, required)
-        The name of the CORSIKA IACT file resulted from the CORSIKA simulation.
-
-    telescope_indices (list, optional)
-        The list with the telescope indices to be considered in the generation of the histograms.
-        Telescopes that are not in the list will not contribute with photons to the histograms.
-        If the argument is not given, all telescopes are considered.
-
-    individual_telescopes (bool, optional)
-        Indicates whether single histograms are generated for the individual telescopes, or if
-        a master histogram is generated for all the telescopes together.
-        If the argument is not given, the Cherenkov photons from the given telescopes are considered
-        together in the same histograms.
-
-    hist_config (hdf5 or dict, optional)
-        The configuration used for generating the histograms.
-        It includes information about the bin sizes, the ranges, scale of the plot and units.
-        By construction, three major histograms are created to start with:
-        - hist_direction (2D): Directive cosines (x and y) for the incoming photons;
-        - hist_position (3D): position x, position y, and wavelength;
-        - hist_time_altitude (2D): time of arrival and altitude of emission;
-
-    If the argument is not given, the default configuration is generated:
-
-    .. code-block:: console
-
-        hist_direction:
-            x axis: {bins: 100, scale: linear, start: -1, stop: 1}
-            y axis: {bins: 100, scale: linear, start: -1, stop: 1}
-
-        hist_position:
-            x axis:
-                bins: 100
-                scale: linear
-                start: !astropy.units.Quantity
-                    unit: &id001 m
-                    value: -1000.0
-                stop: &id002 !astropy.units.Quantity
-                    unit: *id001
-                    value: 1000.0
-            y axis:
-                bins: 100
-                scale: linear
-                start: !astropy.units.Quantity
-                    unit: *id001
-                    value: -1000.0
-                stop: *id002
-            z axis:
-                bins: 80
-                scale: linear
-                start: !astropy.units.Quantity
-                    unit: nm
-                    value: 200.0
-                stop: !astropy.units.Quantity
-                    unit: *id003
-                    value: 1000.0
-        hist_time_altitude:
-            x axis:
-                bins: 100
-                scale: linear
-                start: !astropy.units.Quantity
-                    unit: ns
-                    value: -2000.0
-                stop: !astropy.units.Quantity
-                    unit: *id004
-                    value: 2000.0
-            y axis:
-                bins: 100
-                scale: linear
-                start: !astropy.units.Quantity
-                    unit: km
-                    value: 120.0
-                stop: !astropy.units.Quantity
-                    unit: *id005
-                    value: 0.0
-
-
-    pdf (bool, optional)
-        If set, histograms are saved into pdf files.
-        One pdf file contains all the histograms for the Cherenkov photons.
-        The name of the file is controlled via hdf5_file_name.
-        If event_1d_histograms and event_2d_histograms are used, two separate pdf files might be
-        created to accommodate the histograms for the CORSIKA event header elements. The core names
-        of these output pdf files are also given by hdf5_file_name argument with the addition of
-        'event_1d_histograms' and 'event_2d_histograms'.
-
+    input_files (str, required)
+        The name(s) of the CORSIKA IACT file(s) resulted from the CORSIKA simulation.
 
-    hdf5 (bool, optional)
-        If set, histograms are saved into hdf5 files.
+    pdf_file_name (str, optional)
+        The name of the output pdf file to save the histograms. If not provided,
+        the histograms are only shown on screen.
 
-    hdf5_file_name (str, optional)
-        The name of the output hdf5 data (without the path).
-        It requires the --hdf5 flag.
-        If not given, hdf5_file_name takes the name from the input IACT file (input_file).
-        If the output hdf5_file_name file already exists, the tables associated to the chosen
-        flags (e.g. hdf5, event_1d_histograms, event_2d_histograms) will be overwritten. The
-        remaining tables, if any, will stay untouched.
-
-
-    event_1d_histograms (str, optional)
-        Generate 1D histograms for elements given in --event_1d_histograms from the CORSIKA event
-        header and save into hdf5/pdf files.
-        It allows more than one argument, separated by simple spaces.
-        Usage: --event_1d_histograms first_interaction_height total_energy.
-
-    event_2d_histograms (str, optional)
-        Generate 2D histograms for elements given in --event_2d_histograms from the CORSIKA event
-        header and save into hdf5/pdf files.
-        It allows more than one argument, separated by simple spaces.
-        The elements are grouped into pairs and the 2D histograms are generated always for two
-        subsequent elements.
-        For example, --event_2d_histograms first_interaction_height total_energy zenith azimuth
-        will generate one 2D histogram for first_interaction_height total_energy and another 2D
-        histogram for zenith and azimuth.
+    file_labels (str, optional)
+        Labels for the input files (in the same order as input_files). If not provided,
+        the file names are used as labels.
 
     Example
     -------
-    Generate the histograms for a test IACT file:
+    Fill and plot histograms for a test IACT file:
 
      .. code-block:: console
 
-        simtools-generate-corsika-histograms --iact_file /workdir/external/simtools/\\
+        simtools-generate-corsika-histograms --input_files /workdir/external/simtools/\\
         tests/resources/tel_output_10GeV-2-gamma-20deg-CTAO-South.corsikaio \\
-            --pdf --hdf5 \\
-            --event_2d_histograms zenith azimuth --event_1d_histograms total_energy
+            --pdf_file_name test.pdf
+
+    Fill and plot histograms for several files:
+
+     .. code-block:: console
 
-    Expected final print-out message:
+        simtools-generate-corsika-histograms --input_files file1 file 2 \\
+            --file_lablels label1 label2 \\
+            --pdf_file_name test.pdf
 
-    .. code-block:: console
+    Notes
+    -----
+    The typical use case of this application is to generate lateral photon density distribution
+    to compare different CORSIKA simulation settings or different CORSIKA versions. The following
+    steps are recommended:
 
-        INFO::generate_corsika_histograms(l358)::main::Finalizing the application.
-        Total time needed: 8s.
+        - generate a 'star'-like array of telescopes with the 'simtools-generate-regular-arrays'
+          application. There should be a sufficient number of telescopes (e.g. 50 or more) in the
+          layout with non-overlapping telescope definitions
+
+        - run CORSIKA simulations with the desired settings using this telescope layout (use the
+          'overwrite_model_parameters' option to point to the generated layout simulation model
+          change file (in the format given by 'simulation_models_info.schema.yml').
+
+        - run this application to generate the histograms for the produced CORSIKA IACT output
 """
 
-import time
+from astropy import units as u
 
 from simtools.application_control import get_application_label, startup_application
 from simtools.configuration import configurator
 from simtools.corsika.corsika_histograms import CorsikaHistograms
+from simtools.visualization import plot_corsika_histograms
 
 
 def _parse():
@@ -177,117 +81,63 @@ def _parse():
         label=get_application_label(__file__),
         description="Generate histograms for the Cherenkov photons saved in the CORSIKA IACT file.",
     )
-
     config.parser.add_argument(
-        "--iact_file",
-        help="Name of the CORSIKA IACT file from which to generate the histograms.",
+        "--input_files",
+        help="Name(s) of the CORSIKA IACT file(s) to process",
         type=str,
+        nargs="+",
         required=True,
     )
-
     config.parser.add_argument(
-        "--telescope_indices",
-        help="List of telescope indices to be considered in the generation of the histograms",
+        "--file_labels",
+        help="Labels for the input files (in the same order as input_files)",
         type=str,
-        required=False,
         nargs="+",
-        default=None,
+        required=None,
     )
-
-    config.parser.add_argument(
-        "--individual_telescopes",
-        help="if False, the histograms are filled for all given telescopes together, otherwise"
-        "one histogram is set for each telescope separately.",
-        action="store_true",
-        required=False,
-        default=False,
-    )
-
     config.parser.add_argument(
-        "--hist_config",
-        help="hdf5 file with the configuration parameters to create the histograms.",
+        "--normalization",
+        help="Normalization method for histograms. Options: 'per-telescope', 'per-bin'",
         type=str,
-        required=False,
-        default=None,
-    )
-
-    config.parser.add_argument(
-        "--pdf", help="Save histograms into a pdf file.", action="store_true", required=False
+        choices=["per-telescope", "per-bin"],
+        default="per-telescope",
     )
-
     config.parser.add_argument(
-        "--hdf5", help="Save histograms into hdf5 files.", action="store_true", required=False
+        "--axis_distance",
+        help=(
+            "Distance from x/y axes to consider when calculating "
+            "the lateral density profiles (in meters)."
+        ),
+        type=float,
+        default=1000.0,
     )
-
     config.parser.add_argument(
-        "--hdf5_file_name",
-        help="Name of the hdf5 file where to save the histograms.",
+        "--pdf_file_name",
+        help="Save histograms into a pdf file.",
         type=str,
-        required=False,
-        default=None,
+        required=None,
     )
-
-    config.parser.add_argument(
-        "--event_1d_histograms",
-        help="The keys from the CORSIKA event header to be used for the generation of 1D "
-        "histograms. The available choices can been found in the all_event_keys attribute of"
-        "the CorsikaHistograms.",
-        required=False,
-        default=None,
-        nargs="*",
-    )
-
-    config.parser.add_argument(
-        "--event_2d_histograms",
-        help="The keys from the CORSIKA event header to be used for the generation of 2D "
-        "histograms. The available choices can been found in the all_event_keys attribute of"
-        "the CorsikaHistograms.",
-        required=False,
-        default=None,
-        nargs="*",
-    )
-
-    config_parser, _ = config.initialize(db_config=False, paths=True)
-
-    if (
-        not config_parser["pdf"]
-        and not config_parser["hdf5"]
-        and not config_parser["event_1d_histograms"]
-        and not config_parser["event_2d_histograms"]
-    ):
-        config.parser.error(
-            "At least one argument is required: --pdf, --hdf5, --event_1d_histograms, or "
-            "--event_2d_histograms."
-        )
-
-    return config_parser, _
+    return config.initialize(db_config=False, paths=True)
 
 
 def main():
-    """Generate a set of histograms for the Cherenkov photons saved in the CORSIKA IACT file."""
+    """Generate a set of histograms for the Cherenkov photons from CORSIKA IACT file(s)."""
     app_context = startup_application(_parse)
 
-    initial_time = time.time()
-
-    corsika_histograms_instance = CorsikaHistograms(
-        app_context.args["iact_file"],
-        output_path=app_context.io_handler.get_output_directory(),
-        hdf5_file_name=app_context.args["hdf5_file_name"],
-    )
-    corsika_histograms_instance.run_export_pipeline(
-        individual_telescopes=app_context.args["individual_telescopes"],
-        hist_config=app_context.args["hist_config"],
-        indices_arg=app_context.args["telescope_indices"],
-        write_pdf=app_context.args["pdf"],
-        write_hdf5=app_context.args["hdf5"],
-        event1d=app_context.args["event_1d_histograms"],
-        event2d=app_context.args["event_2d_histograms"],
-        test=app_context.args["test"],
-    )
+    all_histograms = []
+    for input_file in app_context.args["input_files"]:
+        corsika_histograms = CorsikaHistograms(
+            input_file,
+            normalization_method=app_context.args["normalization"],
+            axis_distance=app_context.args["axis_distance"] * u.m,
+        )
+        corsika_histograms.fill()
+        all_histograms.append(corsika_histograms)
 
-    final_time = time.time()
-    app_context.logger.info(
-        f"Finalizing the application. Total time needed: {round(final_time - initial_time)}s."
+    plot_corsika_histograms.export_all_photon_figures_pdf(
+        all_histograms,
+        app_context.io_handler.get_output_file(app_context.args.get("pdf_file_name")),
+        app_context.args.get("file_labels"),
     )
 
 

simtools/applications/generate_regular_arrays.py

@@ -1,15 +1,25 @@
 #!/usr/bin/python3
 
 """
-Make a regular array of telescopes and save it as astropy table.
+Make a regular array of telescopes and save it to file.
 
-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.
+Arrays can consist of single (central) telescopes, square grids or star-like (with
+telescopes arranged on main axes) patterns.  All telescopes in the array are of
+the same type and are placed at regular distances.
 
-The array layout files created will be available at the data/layout directory.
+Output files are saved as astropy tables in ASCII ECSV format and in the simtools format
+required to be used for the overwrite model parameter configuration.
 
 Command line arguments
 ----------------------
+telescope_type (str)
+    Type of telescope (e.g., LST, MST, SST).
+n_telescopes (int)
+    Number of telescopes in the array.
+telescope_distance (float)
+    Distance between telescopes in the array (in meters).
+array_shape (str)
+    Shape of the array ('square', 'star').
 site (str, required)
     observatory site (e.g., North or South).
 model_version (str, optional)
@@ -27,28 +37,42 @@ Runtime < 10 s.
 from pathlib import Path
 
 import astropy.units as u
-from astropy.table import QTable
 
 import simtools.data_model.model_data_writer as writer
 from simtools.application_control import get_application_label, startup_application
 from simtools.configuration import configurator
-from simtools.utils import names
-
-# Telescope distances for 4 tel square arrays
-# !HARDCODED
-telescope_distance = {"LST": 57.5 * u.m, "MST": 70 * u.m, "SST": 80 * u.m}
+from simtools.layout.array_layout_utils import create_regular_array, write_array_elements_info_yaml
 
 
 def _parse():
     config = configurator.Configurator(
         label=get_application_label(__file__),
-        description=(
-            "Generate a regular array of telescope and save as astropy table.\n"
-            "Default telescope distances for 4 telescope square arrays are: \n"
-            f"  LST: {telescope_distance['LST']}\n"
-            f"  MST: {telescope_distance['MST']}\n"
-            f"  SST: {telescope_distance['SST']}\n"
-        ),
+        description=("Generate a regular array of telescope and save as astropy table."),
+    )
+    config.parser.add_argument(
+        "--telescope_type",
+        help="Type of telescope (e.g., LST, MST, SST).",
+        type=str,
+        default="LST",
+    )
+    config.parser.add_argument(
+        "--n_telescopes",
+        help="Number of telescopes in the array.",
+        type=int,
+        default=4,
+    )
+    config.parser.add_argument(
+        "--telescope_distance",
+        help="Distance between telescopes in the array (in meters).",
+        type=float,
+        default=50.0,
+    )
+    config.parser.add_argument(
+        "--array_shape",
+        help="Shape of the array (e.g., 'square', 'star').",
+        type=str,
+        default="square",
+        choices=["square", "star"],
     )
     return config.initialize(
         db_config=False, simulation_model=["site", "model_version"], output=True
@@ -56,61 +80,44 @@ def _parse():
 
 
 def main():
-    """Create layout array files (ecsv) of regular arrays."""
+    """Create layout array files of regular arrays."""
     app_context = startup_application(_parse)
 
-    if app_context.args["site"] == "South":
-        array_list = ["1SST", "4SST", "1MST", "4MST", "1LST", "4LST"]
-    else:
-        array_list = ["1MST", "4MST", "1LST", "4LST"]
-
-    for array_name in array_list:
-        app_context.logger.info(f"Processing array {array_name}")
-
-        tel_name, pos_x, pos_y, pos_z = [], [], [], []
-        tel_size = array_name[1:4]
-
-        # Single telescope at the center
-        if array_name[0] == "1":
-            tel_name.append(
-                names.generate_array_element_name_from_type_site_id(
-                    tel_size, app_context.args["site"], "01"
-                )
-            )
-            pos_x.append(0 * u.m)
-            pos_y.append(0 * u.m)
-            pos_z.append(0 * u.m)
-        # 4 telescopes in a regular square grid
-        else:
-            for i in range(1, 5):
-                tel_name.append(
-                    names.generate_array_element_name_from_type_site_id(
-                        tel_size, app_context.args["site"], f"0{i}"
-                    )
-                )
-                pos_x.append(telescope_distance[tel_size] * (-1) ** (i // 2))
-                pos_y.append(telescope_distance[tel_size] * (-1) ** (i % 2))
-                pos_z.append(0 * u.m)
-
-        table = QTable(meta={"array_name": array_name, "site": app_context.args["site"]})
-        table["telescope_name"] = tel_name
-        table["position_x"] = pos_x
-        table["position_y"] = pos_y
-        table["position_z"] = pos_z
-        table.sort("telescope_name")
-        table.pprint()
-
-        output_file = app_context.args.get("output_file")
-        if output_file:
-            output_path = Path(output_file)
-            output_file = output_path.with_name(
-                f"{output_path.stem}-{app_context.args['site']}-{array_name}{output_path.suffix}"
-            )
-        writer.ModelDataWriter.dump(
-            args_dict=app_context.args,
+    n_tel = app_context.args["n_telescopes"]
+    tel_type = app_context.args["telescope_type"]
+    tel_dist = app_context.args["telescope_distance"] * u.m
+    shape = app_context.args["array_shape"]
+
+    array_name = f"{n_tel}{tel_type}-{shape}"
+    app_context.logger.info(f"Processing array {array_name}")
+
+    array_table = create_regular_array(
+        array_name,
+        app_context.args["site"],
+        n_telescopes=n_tel,
+        telescope_type=tel_type,
+        telescope_distance=tel_dist,
+        shape=shape,
+    )
+
+    output_file = app_context.args.get("output_file")
+    if output_file:
+        output_path = Path(output_file)
+        output_file = output_path.with_name(
+            f"{output_path.stem}-{app_context.args['site']}-{array_name}{output_path.suffix}"
+        )
+
+        data_writer = writer.ModelDataWriter(
             output_file=output_file,
-            metadata=None,
-            product_data=table,
+            output_file_format=app_context.args.get("output_file_format", "ascii.ecsv"),
+        )
+        data_writer.write(metadata=None, product_data=array_table)
+
+        write_array_elements_info_yaml(
+            array_table,
+            app_context.args["site"],
+            app_context.args["model_version"],
+            Path(data_writer.output_file).with_suffix(".info.yml"),
         )
 
 

simtools/applications/generate_simtel_event_data.py

@@ -130,7 +130,7 @@ from simtools.application_control import get_application_label, startup_applicat
 from simtools.configuration import configurator
 from simtools.data_model.metadata_collector import MetadataCollector
 from simtools.io import io_handler, table_handler
-from simtools.simtel.simtel_io_event_writer import SimtelIOEventDataWriter
+from simtools.sim_events.writer import EventDataWriter
 
 
 def _parse():
@@ -173,7 +173,7 @@ def main():
         return
 
     output_filepath = io_handler.IOHandler().get_output_file(app_context.args["output_file"])
-    generator = SimtelIOEventDataWriter(files, app_context.args["max_files"])
+    generator = EventDataWriter(files, app_context.args["max_files"])
     tables = generator.process_files()
     table_handler.write_tables(tables, output_filepath, overwrite_existing=True)
     MetadataCollector.dump(

simtools/applications/maintain_simulation_model_add_production.py

@@ -28,8 +28,8 @@ The following example applies a patch update with changes defined in a YAML file
 
 .. code-block:: console
 
-    simtools-maintain-simulation-model-add-new-production \\
-        --model_path ../simulation-models-dev/simulation-models/ \\
+    simtools-maintain-simulation-model-add-production \\
+        --model_path ../simulation-models-dev \\
         --model_version 6.0.2
 
 """

simtools/applications/maintain_simulation_model_write_array_element_positions.py

@@ -0,0 +1,87 @@
+#!/usr/bin/python3
+"""
+    Read array element positions from file and write model parameter files for each element.
+
+    This is an application for experts and should not be used by the general user.
+    Reading of input is fine-tuned to the array element files as provided by CTAO.
+
+    Writes one model parameter file per array element into a directory structure compatible
+    with the simtools model parameter repository.
+
+    Command line arguments
+
+    input : str
+        File containing a table of array element positions.
+    repository_path : str
+        Path of local copy of model parameter repository.
+    parameter_version : str
+        Parameter version.
+    coordinate_system : str
+        Coordinate system of array element positions (ground or utm).
+
+    Examples
+    --------
+    Add array element positions to repository (ground coordinates):
+
+    .. code-block:: console
+
+        simtools-maintain-simulation-model-write-array-element-positions \
+            --input tests/resources/telescope_positions-North-ground.ecsv \
+            --output_path /path/to/repository \
+            --parameter_version 0.1.0 \
+            --coordinate_system ground
+
+    Add array element positions to repository (utm coordinates):
+
+    .. code-block:: console
+
+        simtools-maintain-simulation-model-write-array-element-positions \
+            --input tests/resources/telescope_positions-North-utm.ecsv \
+            --output_path /path/to/repository \
+            --parameter_version 0.1.0 \
+            --coordinate_system utm
+
+"""
+
+from simtools.application_control import get_application_label, startup_application
+from simtools.configuration import configurator
+from simtools.layout.array_layout_utils import write_array_elements_from_file_to_repository
+
+
+def _parse():
+    """Parse command line configuration."""
+    config = configurator.Configurator(
+        label=get_application_label(__file__),
+        description="Add array element positions to model parameter repository",
+    )
+    config.parser.add_argument(
+        "--input",
+        help="File containing a table of array element positions.",
+        required=False,
+    )
+    config.parser.add_argument(
+        "--coordinate_system",
+        help="Coordinate system of array element positions (utm or ground).",
+        default="ground",
+        required=False,
+        type=str,
+        choices=["ground", "utm"],
+    )
+
+    return config.initialize(db_config=True, output=True, simulation_model=["parameter_version"])
+
+
+def main():
+    """Application main."""
+    app_context = startup_application(_parse)
+
+    write_array_elements_from_file_to_repository(
+        coordinate_system=app_context.args["coordinate_system"],
+        input_file=app_context.args["input"],
+        repository_path=app_context.args["output_path"],
+        parameter_version=app_context.args["parameter_version"],
+    )
+
+
+if __name__ == "__main__":
+    main()