Merge branch 'main' into docstring-applications-commands

.github/workflows/build-docker-corsika-simtelarray-image.yml

@@ -64,7 +64,7 @@ jobs:
           flavor: latest=true
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64/v8

.github/workflows/build-docker-images.yml

@@ -75,7 +75,7 @@ jobs:
           flavor: latest=true
 
       - name: Build Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         if: matrix.type == 'prod'
         with:
           context: .
@@ -104,7 +104,7 @@ jobs:
         shell: /usr/bin/bash -e {0}
 
       - name: Push Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           build-args: BUILD_BRANCH=${{ env.BUILD_BRANCH }}

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
         args: ["--line-length=100"]
   - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff
-    rev: v0.4.6
+    rev: v0.4.9
     hooks:
       - id: ruff
         args: ["--fix"]

docker/README.md

@@ -45,7 +45,7 @@ To startup a container to use bash
 docker run --rm -it --env-file .env -v "$(pwd):/workdir/external" ghcr.io/gammasim/simtools-prod:latest bash
 ```
 
-In the container, simtools applications are installed and can be called directly (e.g., `simtools-print-array-elements -h`).
+In the container, simtools applications are installed and can be called directly (e.g., `simtools-convert-geo-coordinates-of-array-elements -h`).
 This example uses the docker syntax to mount your local directory for file access.
 
 The following example runs an application inside the container and writes the output into a directory of the local files system,
@@ -54,7 +54,7 @@ The following example runs an application inside the container and writes the ou
 docker run --rm -it --env-file .env \
     -v "$(pwd):/workdir/external" \
     ghcr.io/gammasim/simtools-prod:latest \
-    simtools-print-array-elements \
+    simtools-convert-geo-coordinates-of-array-elements \
     --array_element_list ./simtools/tests/resources/telescope_positions-North-utm.ecsv \
     --export corsika --use_corsika_telescope_height \
     --output_path /workdir/external/

docs/source/applications.md

@@ -37,6 +37,7 @@ end users, but for developers working on the database schema.
 
 calculate_trigger_rate
 convert_all_model_parameters_from_simtel
+convert_geo_coordinates_of_array_elements
 convert_model_parameter_from_simtel
 db_add_file_to_db
 db_add_model_parameters_from_repository_to_db
@@ -53,7 +54,6 @@ generate_default_metadata
 generate_simtel_array_histograms
 generate_regular_arrays
 plot_array_layout
-print_array_elements
 simulate_light_emission
 simulate_prod
 simulate_showers_for_trigger_rates

docs/source/convert_geo_coordinates_of_array_elements.rst

@@ -0,0 +1,6 @@
+
+convert_geo_coordinates_of_array_elements
+=========================================
+
+.. automodule:: convert_geo_coordinates_of_array_elements
+   :members:

docs/source/developer_guidelines.md

@@ -77,6 +77,9 @@ Tests might pass just because they run after an unrelated test. In order to test
 Check the test coverage with `pytest -vv -n auto tests/unit_tests/ tests/integration_tests/ --cov`.
 Add the `--cov-report html` option to generate a coverage report in HTML format.
 
+It might be quite useful to test a single application while developing.
+This can be done with e.g. `pytest -v -k "simtools-convert-all-model-parameters-from-simtel" tests/integration_tests/test_applications_from_config.py` to run all the integrations tests for the `simtools-convert-all-model-parameters-from-simtel` application.
+Alternatively, run `pytest -v -k "simtools-convert-all-model-parameters-from-simtel_num_gains" tests/integration_tests/test_applications_from_config.py` to run the tool for the specific test called `num_gains`. Test names are found in the yml files in the `tests/integration_tests/config` directory.
 ## Writing Applications
 
 Applications are command-line tools that should be built of the simtools library.

docs/source/getting_started.md

@@ -98,7 +98,7 @@ docker run --rm -it --env-file .env \
     ghcr.io/gammasim/simtools-prod:latest bash
 ```
 
-In the container, simtools applications are installed and can be called directly (e.g., `simtools-print-array-elements -h`).
+In the container, simtools applications are installed and can be called directly (e.g., `simtools-convert-geo-coordinates-of-array-elements -h`).
 This example uses the docker syntax to mount your local directory.
 
 The following example runs an application inside the container and writes the output into a directory of the local files system,
@@ -107,7 +107,7 @@ The following example runs an application inside the container and writes the ou
 docker run --rm -it --env-file .env \
     -v "$(pwd):/workdir/external" \
     ghcr.io/gammasim/simtools-prod:latest \
-    simtools-print-array-elements \
+    simtools-convert-geo-coordinates-of-array-elements \
     --array_element_list ./simtools/tests/resources/telescope_positions-North-utm.ecsv \
     --export corsika --use_corsika_telescope_height \
     --output_path /workdir/external/

pyproject.toml

@@ -66,6 +66,7 @@ urls."documentation" = "https://gammasim.github.io/simtools/"
 urls."repository" = "https://github.com/gammasim/simtools"
 scripts.simtools-calculate-trigger-rate = "simtools.applications.calculate_trigger_rate:main"
 scripts.simtools-convert-all-model-parameters-from-simtel = "simtools.applications.convert_all_model_parameters_from_simtel:main"
+scripts.simtools-convert-geo-coordinates-of-array-elements = "simtools.applications.convert_geo_coordinates_of_array_elements:main"
 scripts.simtools-convert-model-parameter-from-simtel = "simtools.applications.convert_model_parameter_from_simtel:main"
 scripts.simtools-db-add-file-to-db = "simtools.applications.db_add_file_to_db:main"
 scripts.simtools-db-add-model-parameters-from-repository-to-db = "simtools.applications.db_add_model_parameters_from_repository_to_db:main"
@@ -82,7 +83,6 @@ scripts.simtools-generate-default-metadata = "simtools.applications.generate_def
 scripts.simtools-generate-regular-arrays = "simtools.applications.generate_regular_arrays:main"
 scripts.simtools-generate-simtel-array-histograms = "simtools.applications.generate_simtel_array_histograms:main"
 scripts.simtools-plot-array-layout = "simtools.applications.plot_array_layout:main"
-scripts.simtools-print-array-elements = "simtools.applications.print_array_elements:main"
 scripts.simtools-production = "simtools.applications.production:main"
 scripts.simtools-simulate-light-emission = "simtools.applications.simulate_light_emission:main"
 scripts.simtools-simulate-prod = "simtools.applications.simulate_prod:main"

simtools/applications/print_array_elements.py → simtools/applications/convert_geo_coordinates_of_array_elements.py

@@ -1,58 +1,53 @@
 #!/usr/bin/python3
-"""
-    Summary
-    -------
-    Convert and print a list of array element positions in different coordinate \
-    systems relevant for CTAO.
+"""Convert and print a list of array element positions in different coordinate systems.
 
     Description
     -----------
 
-    This application converts a list of array element positions in different CTAO \
-    coordinate systems.
-
+    Convert array element positions in different CTAO coordinate systems.
     Available coordinate systems are:
 
     1. UTM system
-    2. ground system (similar to sim_telarray system with x-axis pointing toward \
-        geographic north and y-axis pointing towards the west); altitude relative \
-        to the CORSIKA observation level.
+    2. ground system (similar to sim_telarray system with x-axis pointing toward geographic north
+       and y-axis pointing towards the west); altitude relative to the CORSIKA observation level.
+       Altitude is the height of the elevation rotation axis (plus some possible mirror offset).
     3. Mercator system
 
     Command line arguments
     ----------------------
     input (str)
-        File name with list of array element positions
+        File name with list of array element positions.
+        Input can be given as astropy table file (ecsv) or a single array element in
+        a json file.
     print (str)
-        Print requested coordinate system; possible are ground, utm, mercator
+        Print in requested coordinate system; possible are ground, utm, mercator
     export (str)
-        Export array element list to file in requested coordinate system; \
-            possible are ground, utm, mercator
+        Export array element list to file in requested coordinate system;
+          possible are ground, utm, mercator
     select_assets (str)
         Select a subset of array elements / telescopes (e.g., MSTN, LSTN)
 
-
     Example
     -------
-    Print a list of array elements using a list of telescope positions in UTM coordinates.
+    Convert a list of array elements using a list of telescope positions in UTM coordinates.
 
     .. code-block:: console
 
-        simtools-print-array-elements \\
-            --input tests/resources/telescope_positions-North-utm.ecsv \\
+        simtools-convert-geo-coordinates-of-array-elements
+            --input tests/resources/telescope_positions-North-utm.ecsv
             --print ground
 
     The converted list of telescope positions in ground coordinates is printed to the screen.
 
-    The following example converts a list of telescope positions in UTM coordinates \
-    and writes the output to a file in ground (sim_telarray) coordinates. Also selects \
+    The following example converts a list of telescope positions in UTM coordinates
+    and writes the output to a file in ground (sim_telarray) coordinates. Also selects
     only a subset of the array elements (telescopes; ignore calibration devices):
 
     .. code-block:: console
 
-        simtools-print-array-elements \\
-            --input tests/resources/telescope_positions-North-utm.ecsv \\
-            --export ground \\
+        simtools-convert-geo-coordinates-of-array-elements
+            --input tests/resources/telescope_positions-North-utm.ecsv
+            --export ground
             --select_assets LSTN
 
     Expected output is a ecsv file in the directory printed to the screen.
@@ -71,7 +66,7 @@
 
 def _parse(label=None, description=None):
     """
-    Parse command line configuration
+    Parse command line configuration.
 
     Parameters
     ----------
@@ -84,15 +79,13 @@ def _parse(label=None, description=None):
     -------
     CommandLineParser
         Command line parser object
-
     """
-
     config = configurator.Configurator(label=label, description=description)
 
     config.parser.add_argument(
         "--input",
         help="list of array element positions",
-        required=False,
+        required=True,
     )
     config.parser.add_argument(
         "--input_meta",
@@ -137,11 +130,12 @@ def _parse(label=None, description=None):
         action="store_true",
     )
     return config.initialize(
-        output=True, require_command_line=True, db_config=True, simulation_model="version"
+        output=True, require_command_line=True, db_config=True, simulation_model=["version", "site"]
     )
 
 
 def main():
+    """Print a list of array elements."""
     label = Path(__file__).stem
     data_model_name = "array_coordinates"
     args_dict, db_config = _parse(
@@ -152,12 +146,22 @@ def main():
     logger = logging.getLogger()
     logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
 
-    metadata = MetadataCollector(args_dict=args_dict, data_model_name=data_model_name)
+    json_type = args_dict.get("input", "").endswith(".json")
+    # simplified metadata treatment for model parameter json files
+    if json_type:
+        site = args_dict.get("site", None)
+        top_level_meta = None
+        validate_schema_file = None
+    else:
+        metadata = MetadataCollector(args_dict=args_dict, data_model_name=data_model_name)
+        site = metadata.get_site(from_input_meta=True)
+        top_level_meta = metadata.top_level_meta
+        validate_schema_file = metadata.get_data_model_schema_file_name()
 
     layout = array_layout.ArrayLayout(
         mongo_db_config=db_config,
         model_version=args_dict["model_version"],
-        site=metadata.get_site(from_input_meta=True),
+        site=site,
         telescope_list_file=args_dict["input"],
         telescope_list_metadata_file=args_dict["input_meta"],
         validate=not args_dict["skip_input_validation"],
@@ -166,13 +170,16 @@ def main():
     layout.convert_coordinates()
 
     if args_dict["export"] is not None:
+        product_data = (
+            layout.export_one_telescope_as_json(crs_name=args_dict["export"])
+            if json_type
+            else layout.export_telescope_list_table(crs_name=args_dict["export"])
+        )
         writer.ModelDataWriter.dump(
             args_dict=args_dict,
-            metadata=metadata.top_level_meta,
-            product_data=layout.export_telescope_list_table(
-                crs_name=args_dict["export"],
-            ),
-            validate_schema_file=metadata.get_data_model_schema_file_name(),
+            metadata=top_level_meta,
+            product_data=product_data,
+            validate_schema_file=validate_schema_file,
         )
     else:
         layout.print_telescope_list(