gammasimtools 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

simtools/applications/simulate_flasher.py

@@ -1,48 +1,59 @@
 #!/usr/bin/python3
 
 r"""
-Simulate flasher devices using the light emission package.
+Simulate flasher devices used e.g. for camera flat fielding.
 
-Run the application in the command line.
+The flasher simulation allows for two different run modes:
+
+1. Direct injection of light into the camera (bypassing the telescope optics).
+2. Simulation of the full light path (using the light-emission package from sim_telarray).
+
+The direct injection mode uses a simplified model for the flasher light source. Both run modes
+provide events in sim_telarray format that can be processed by standard analysis steps or
+visualized using e.g. the 'simtools-plot-simtel-events' application.
 
 Example Usage
 -------------
 
-1. Simulate flashers for a telescope:
+1. Simulate flashers for a telescope (direct injection):
+
+    .. code-block:: console
+
+        simtools-simulate-flasher --run_mode direct_injection \
+        --light_source MSFx-FlashCam --model_version 6.0.0 \
+        --array_layout_name subsystem_msts --site South \
+        --run_number 3
+
+2. Simulate flashers for a telescope (detailed simulation):
 
     .. code-block:: console
 
-        simtools-simulate-flasher --telescope MSTN-04 --site North \
-        --flasher FLSN-01 --model_version 6.0.0
+        simtools-simulate-flasher --run_mode full_simulation \
+        --light_source MSFx-FlashCam --model_version 6.0.0 \
+        --telescope MSTS-04 --site South
 
 Command Line Arguments
 ----------------------
+run_mode (str, required)
+    Run mode, either "direct_injection" or "full_simulation".
 telescope (str, required)
     Telescope model name (e.g. LSTN-01, MSTN-04, SSTS-04, ...)
 site (str, required)
     Site name (North or South).
-flasher (str, required)
-    Flasher device in array, e.g., FLSN-01.
+light_source (str, required)
+    Calibration light source, e.g., MSFx-FlashCam
 number_of_events (int, optional):
     Number of events to simulate (default: 1).
 output_prefix (str, optional):
     Prefix for output files (default: empty).
 model_version (str, optional)
     Version of the simulation model.
-
-Example
--------
-
-Simulate flashers for MSTN-04:
-
-.. code-block:: console
-
-    simtools-simulate-flasher --telescope MSTN-04 --site North \
-    --flasher FLSN-01 --model_version 6.0.0
-
-Expected Output:
-    The simulation will run the light emission package for the flasher
-    devices and produce the output files.
+array_layout_name (str, optional)
+    Name of the array layout to use (required for direct injection mode).
+run_number (int, optional)
+    Run number to use (default: 1, required for direct injection mode).
+telescope (str, optional)
+    Telescope name (required for full simulation mode).
 """
 
 import logging
@@ -50,91 +61,82 @@ from pathlib import Path
 
 import simtools.utils.general as gen
 from simtools.configuration import configurator
-from simtools.model.flasher_model import FlasherModel
-from simtools.model.model_utils import initialize_simulation_models
 from simtools.simtel.simulator_light_emission import SimulatorLightEmission
+from simtools.simulator import Simulator
 
 
 def _parse(label):
     """Parse command line configuration."""
-    config = configurator.Configurator(
-        label=label,
-        description=("Simulate flasher devices using the light emission package."),
+    config = configurator.Configurator(label=label, description="Simulate flasher devices.")
+    config.parser.add_argument(
+        "--run_mode",
+        help="Flasher simulation run mode",
+        type=str,
+        choices=["direct_injection", "full_simulation"],
+        required=True,
+        default="direct_injection",
     )
     config.parser.add_argument(
-        "--flasher",
-        help="Flasher device in array associated with a specific telescope, i.e. FLSN-01",
+        "--light_source",
+        help="Flasher device associated with a specific telescope, i.e. MSFx-FlashCam",
         type=str,
         required=True,
     )
     config.parser.add_argument(
-        "--number_events",
-        help="Number of number_events to simulate (default: 1)",
+        "--number_of_events",
+        help="Number of flasher events to simulate",
         type=int,
         default=1,
         required=False,
     )
     config.parser.add_argument(
         "--output_prefix",
-        help="Prefix for output files (default: empty)",
+        help="Prefix for output files",
         type=str,
         default=None,
         required=False,
     )
-
     return config.initialize(
         db_config=True,
-        simulation_model=["telescope", "model_version"],
-        require_command_line=True,
+        simulation_model=["site", "layout", "telescope", "model_version"],
+        simulation_configuration={
+            "corsika_configuration": ["run_number"],
+            "sim_telarray_configuration": ["all"],
+        },
     )
 
 
-def flasher_configs():
-    """Return default setup for flasher runs (no distances)."""
-    return {"light_source_setup": "layout"}
-
-
 def main():
-    """Run the application."""
+    """Simulate flasher devices."""
     label = Path(__file__).stem
-    logger = logging.getLogger(__name__)
 
     args_dict, db_config = _parse(label)
+    logger = logging.getLogger()
     logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
 
-    telescope_model, site_model = initialize_simulation_models(
-        label=label,
-        db_config=db_config,
-        site=args_dict["site"],
-        telescope_name=args_dict["telescope"],
-        model_version=args_dict["model_version"],
+    logger.info(
+        f"Flasher simulation for telescope {args_dict['telescope']} "
+        f" with light source {args_dict['light_source']} "
+        f" ({args_dict['number_of_events']} events, run mode: {args_dict['run_mode']})"
     )
 
-    flasher_model = FlasherModel(
-        site=args_dict["site"],
-        flasher_device_model_name=args_dict["flasher"],
-        mongo_db_config=db_config,
-        model_version=args_dict["model_version"],
-        label=label,
-    )
-
-    flasher_cfg = flasher_configs()
-
-    sim_runner = SimulatorLightEmission(
-        telescope_model=telescope_model,
-        flasher_model=flasher_model,
-        site_model=site_model,
-        light_emission_config=args_dict,
-        light_source_setup=flasher_cfg["light_source_setup"],
-        simtel_path=args_dict["simtel_path"],
-        light_source_type="flasher",
-        label=args_dict["label"],
-        test=args_dict.get("test", False),
-    )
-
-    sim_runner.run_simulation()
-
-    logger.info("Flasher simulation completed. Use simtools-plot-simtel-number_events for plots.")
+    if args_dict["run_mode"] == "full_simulation":
+        light_source = SimulatorLightEmission(
+            light_emission_config=args_dict,
+            db_config=db_config,
+            label=args_dict.get("label"),
+        )
+    elif args_dict["run_mode"] == "direct_injection":
+        light_source = Simulator(
+            args_dict=args_dict,
+            db_config=db_config,
+            label=args_dict.get("label"),
+        )
+    else:
+        raise ValueError(f"Unsupported run_mode: {args_dict['run_mode']}")
+
+    light_source.simulate()
+    logger.info("Flasher simulation completed.")
 
 
 if __name__ == "__main__":

simtools/applications/simulate_illuminator.py

@@ -1,116 +1,63 @@
 #!/usr/bin/python3
 
 r"""
-Simulate calibration devices using the light emission package.
+Simulate illuminator (distant calibration light source).
 
-Run the application in the command line.
-There are two ways this application can be executed:
+Illuminators are calibration light sources not attached to a particular telescope.
+Two types of illuminators are supported:
 
-1. Illuminator at varying distances.
-2. Illuminator and telescopes at fixed positions as defined in the layout.
+1. Illuminator as foreseen at CTAO with fixed positions as defined in the simulation models
+   database.
+2. Illuminator at a configurable position relative to the array center. Note that in this case
+   the telescope pointing is fixed towards zenith.
 
 Example Usage
 -------------
 
-1. Simulate light emission with varying distances:
+1. Simulate illuminator with positions as defined in the simulation models database:
 
     .. code-block:: console
 
-        simtools-simulate-illuminator --telescope MSTN-04 --site North \
-        --illuminator ILLN-01 --light_source_setup variable \
+        simtools-simulate-illuminator --light_source ILLN-01 \
+        --telescope MSTN-04 --site North \
         --model_version 6.0.0
 
-2. Simulate light emission with telescopes at fixed positions according to the layout:
+2. Simulate at a configurable position (1km above array center) and pointing downwards:
 
     .. code-block:: console
 
-        simtools-simulate-illuminator --telescope MSTN-04 --site North \
-        --illuminator ILLN-01 --light_source_setup layout \
+        simtools-simulate-illuminator --light_source ILLN-01 \
+        --light_source_position 0. 0. 1000. \
+        --light_source_pointing 0. 0. -1. \
+        --telescope MSTN-15 --site North \
         --model_version 6.0.0
 
 Command Line Arguments
 ----------------------
+light_source (str, optional)
+    Illuminator in array, e.g., ILLN-01.
+number_of_events (int, optional)
+    Number of events to simulate.
 telescope (str, required)
     Telescope model name (e.g. LSTN-01, SSTS-design, SSTS-25, ...)
 site (str, required)
     Site name (North or South).
-illuminator (str, optional)
-    Illuminator in array, e.g., ILLN-01.
-light_source_setup (str, optional)
-    Select calibration light source positioning/setup:
-    - "variable" for varying distances.
-    - "layout" for actual telescope positions.
 model_version (str, optional)
     Version of the simulation model.
-off_axis_angle (float, optional)
-    Off axis angle for light source direction.
-number_events (int, optional)
-    Number of events to simulate.
-
-
-Example
--------
-
-Simulate isotropic light source at different distances for the MSTN-04:
-
-.. code-block:: console
-
-    simtools-simulate-illuminator --telescope MSTN-04 --site North \
-    --illuminator ILLN-01 --light_source_setup variable \
-    --model_version 6.0.0    ```
-
-Expected Output:
-
-.. code-block:: console
-
-    light-emission package stage:
-    File '/workdir/external/simtools/simtools-output/light_emission/model/
-        atmprof_ecmwf_north_winter_fixed.dat' registered for atmospheric profile 99.
-    Atmospheric profile 99 to be read from file '/workdir/external/simtools/
-        simtools-output/light_emission/model/atmprof_ecmwf_north_winter_fixed.dat'.
-    Atmospheric profile 99 with 55 levels read from file /workdir/external/
-        simtools/simtools-output/light_emission/model/atmprof_ecmwf_north_winter_fixed.dat
-    Initialize atmosphere ranging from 0.000 to 120.000 km a.s.l.
-    IACT control parameter line: print_events 999 10 100 1000 0
-    Case 1: 1 event with 1e+10 photons.
-    Using IACT/ATMO package version 1.67 (2023-11-10) for CORSIKA 6.999
-    Output file /workdir/external/simtools/simtools-output/light_emission/xyzls.iact.gz
-        not yet created.
-    Telescope output file: '/workdir/external/simtools/simtools-output/
-        light_emission/xyzls.iact.gz'
-    ....
-    ....
-    Sim_telarray stage:
-    Telescope 1 triggered (1/0/0/0, mask 1), summation from 36 to 95 of 105
-    Event end data has been found.
-    Shower of 0.0000 TeV energy was seen in 1 of 1 cases.
-    Photon statistics:
-    All photons:               928518
-    Used photons:              928518
-    Not absorbed/max. Q.E.:    189560
-    Reflected on mirror:        26815
-    Camera hit:                 25574
-    Pixel hit:                  25574
-    Detected:                   20998
-    Trigger statistics:
-    Tel. triggered:             1
-    Tel. + array:               1
-    Early readout:              0
-    Late readout:               0
-    Finish data conversion ...
-    Writing 13 histograms to output file.
-
+light_source_position (float, float, float, optional)
+    Light source position (x,y,z) relative to the array center (ground coordinates) in
+    m. If not set, the position from the simulation model is used.
+light_source_pointing (float, float, float, optional)
+    Light source pointing direction. If not set, the pointing from the simulation model is used.
+output_prefix (str, optional)
+    Prefix for output files (default: empty).
 """
 
 import logging
 from pathlib import Path
 
-import astropy.units as u
-
 import simtools.utils.general as gen
 from simtools.configuration import configurator
-from simtools.model.calibration_model import CalibrationModel
-from simtools.model.model_utils import initialize_simulation_models
 from simtools.simtel.simulator_light_emission import SimulatorLightEmission
 
 
@@ -119,41 +66,38 @@ def _parse(label):
     config = configurator.Configurator(
         label=label,
         description=(
-            "Simulate the light emission by an artificial light source for calibration purposes."
+            "Simulate light emission by a calibration light source (not attached to a telescope)."
         ),
     )
     config.parser.add_argument(
-        "--off_axis_angle",
-        help="Off axis angle for light source direction",
-        type=float,
-        default=0.0,
-        required=False,
-    )
-
-    config.parser.add_argument(
-        "--light_source_setup",
-        help="Select calibration light source positioning/setup: \
-              varying distances (variable), layout positions (layout)",
+        "--light_source",
+        help="Illuminator name, i.e. ILLN-design",
         type=str,
-        choices=["layout", "variable"],
         default=None,
         required=True,
     )
-    config.parser.add_argument(
-        "--distances_ls",
-        help="Light source distance in m (Example --distances_ls 800 1200)",
-        nargs="+",
+    configurable_light_source_args = config.parser.add_argument_group(
+        "Configurable light source position and pointing (override simulation model values)"
+    )
+    configurable_light_source_args.add_argument(
+        "--light_source_position",
+        help="Light source position (x,y,z) relative to the array center (ground coordinates) in m",
+        metavar=("X", "Y", "Z"),
+        nargs=3,
         required=False,
     )
-    config.parser.add_argument(
-        "--illuminator",
-        help="Illuminator in array, i.e. ILLN-design",
-        type=str,
-        default=None,
-        required=True,
+    configurable_light_source_args.add_argument(
+        "--light_source_pointing",
+        help=(
+            "Light source pointing direction "
+            "(Example for pointing downwards: --light_source_pointing 0 0 -1)"
+        ),
+        metavar=("X", "Y", "Z"),
+        nargs=3,
+        required=False,
     )
     config.parser.add_argument(
-        "--number_events",
+        "--number_of_events",
         help="Number of events to simulate",
         type=int,
         default=1,
@@ -173,98 +117,20 @@ def _parse(label):
     )
 
 
-def light_emission_configs(args_dict):
-    """
-    Define default light emission configurations.
-
-    Predefined angular distribution names not requiring to read any table are
-    "Isotropic", "Gauss:<rms>", "Rayleigh", "Cone:<angle>", and "FilledCone:<angle>", "Parallel",
-    with all angles given in degrees, all with respect to the given direction vector
-    (vertically downwards if missing). If the light source has a non-zero length and velocity
-    (in units of the vacuum speed of light), it is handled as a moving source,
-    in the given direction.
-
-    Parameters
-    ----------
-    args_dict: dict
-        Dictionary with command line arguments.
-
-    args_dict: dict
-        Dictionary with command line arguments.
-
-    Returns
-    -------
-    default_config: dict
-        Default light emission configuration.
-    """
-    if args_dict["light_source_setup"] == "variable":
-        cfg = {
-            "x_pos": {"len": 1, "unit": u.Unit("cm"), "default": 0 * u.cm, "names": ["x_position"]},
-            "y_pos": {"len": 1, "unit": u.Unit("cm"), "default": 0 * u.cm, "names": ["y_position"]},
-            "z_pos": {
-                "len": 1,
-                "unit": u.Unit("cm"),
-                "default": [i * 100 for i in [200, 300, 400, 600, 800, 1200, 2000, 4000]] * u.cm,
-                "names": ["z_position"],
-            },
-            "direction": {
-                "len": 3,
-                "unit": u.dimensionless_unscaled,
-                "default": [0, 0, -1],
-                "names": ["direction", "cx,cy,cz"],
-            },
-        }
-        args_dict.update(cfg)
-        return args_dict
-    return args_dict
-
-
 def main():
-    """Simulate light emission."""
+    """Simulate light emission from illuminator."""
     label = Path(__file__).stem
+
     args_dict, db_config = _parse(label)
-    light_emission_config = light_emission_configs(args_dict)
-    print(light_emission_config)
     logger = logging.getLogger()
     logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
 
-    telescope_model, site_model = initialize_simulation_models(
-        label=label,
-        db_config=db_config,
-        site=args_dict["site"],
-        telescope_name=args_dict["telescope"],
-        model_version=args_dict["model_version"],
-    )
-
-    calibration_model = CalibrationModel(
-        site=args_dict["site"],
-        calibration_device_model_name=args_dict["illuminator"],
-        mongo_db_config=db_config,
-        model_version=args_dict["model_version"],
-        label=label,
-    )
-
     light_source = SimulatorLightEmission(
-        telescope_model=telescope_model,
-        calibration_model=calibration_model,
-        site_model=site_model,
-        light_emission_config=light_emission_config,
-        light_source_setup=args_dict["light_source_setup"],
-        simtel_path=args_dict["simtel_path"],
-        light_source_type="illuminator",
+        light_emission_config=args_dict,
+        db_config=db_config,
         label=label,
-        test=args_dict["test"],
     )
-
-    if args_dict["light_source_setup"] == "variable":
-        outputs = light_source.simulate_variable_distances(args_dict)
-    elif args_dict["light_source_setup"] == "layout":
-        outputs = light_source.simulate_layout_positions(args_dict)
-    else:
-        outputs = []
-
-    if outputs:
-        logger.info("Simulation outputs:\n%s", "\n".join(str(p) for p in outputs))
+    light_source.simulate()
 
 
 if __name__ == "__main__":

simtools/applications/{simulate_calibration_events.py → simulate_pedestals.py}

@@ -1,47 +1,35 @@
 #!/usr/bin/python3
 
 r"""
-Simulate calibration events like pedestal or flasher events.
+Simulate pedestal events.
 
-Use sim_telarray to simulate calibration events for an array of telescopes.
-The following types of calibration events are supported:
+Use sim_telarray to simulate pedestal events for an array of telescopes.
+The following types are supported:
 
 * Pedestal events (includes night-sky background and camera noise)
 * Dark pedestal events (closed camera lid, camera noise only)
-* Flasher events (simulated flasher light source)
+* NSB-only pedestal events (open camera lid, night-sky background only, no camera noise)
 
 Example
 -------
 
-Simulate pedestal events for alpha North. The assumed level night-sky background is 2.0 times the
+Simulate pedestal events for Alpha North. The assumed level night-sky background is 2.0 times the
 nominal value. A list of stars can be provided to simulate additional contributions.
 
 .. code-block:: console
 
-    simtools-simulate-calibration-events --run_mode=pedestals \\
+    simtools-simulate-pedestals --run_mode=pedestals \\
         --run_number 10 --number_of_events 1000 \\
         --array_layout_name alpha --site North \\
         --model_version 6.0.0 \\
         --zenith_angle 20 --azimuth_angle 0 \\
         --nsb_scaling_factor 2.0
 
-Simulate flasher events for alpha South. Note that the same flasher configuration is used
-for all telescopes.
-
-.. code-block:: console
-
-    simtools-simulate-calibration-events --run_mode=flasher \\
-        --run_number 10 --number_of_events 1000 \\
-        --array_layout_name subsystem_msts --site South \\
-        --model_version 6.0.0 \\
-        --zenith_angle 20 --azimuth_angle 0 \\
-        --flasher_photons 500 --flasher_var_photons 0.05 \\
-        --flasher_exp_time 1.59 --flasher_sig_time 0.4
 
 Command Line Arguments
 ----------------------
 run_mode (str, required)
-    Run mode, e.g. "pedestals" or "flasher".
+    Run mode, e.g. "pedestals"
 run_number (int, required)
     Run number for the simulation.
 number_of_events (int, required)
@@ -64,15 +52,6 @@ zenith_angle (float, optional)
     Zenith angle in degrees.
 azimuth_angle (float, optional)
     Azimuth angle in degrees.
-flasher_photons (float, optional)
-    Number of photons in the flasher pulse at each photodetector.
-flasher_var_photons (float, optional)
-    Relative variance of the number of photons in the flasher pulse.
-flasher_exp_time (float, optional)
-    Exponential decay time of the flasher pulse in nano-seconds.
-flasher_sig_time (float, optional)
-    Sigma of Gaussian-shaped flasher pulse in nano-seconds.
-
 """
 
 import logging
@@ -91,11 +70,11 @@ def _parse(label):
         help="Calibration run mode",
         type=str,
         required=True,
-        choices=["pedestals", "dark_pedestals", "nsb_only_pedestals", "flasher"],
+        choices=["pedestals", "dark_pedestals", "nsb_only_pedestals"],
     )
     config.parser.add_argument(
         "--number_of_events",
-        help="Number of calibration events to simulate",
+        help="Number of pedestal events to simulate",
         type=int,
         required=True,
     )
@@ -115,31 +94,6 @@ def _parse(label):
         type=str,
         default=None,
     )
-    flasher_args = config.parser.add_argument_group("Flasher configuration")
-    flasher_args.add_argument(
-        "--flasher_photons",
-        help="Number of photons in the flasher pulse at each photodetector.",
-        type=float,
-        default=500.0,
-    )
-    flasher_args.add_argument(
-        "--flasher_var_photons",
-        help="Relative variance of the number of photons in the flasher pulse.",
-        type=float,
-        default=0.05,
-    )
-    flasher_args.add_argument(
-        "--flasher_exp_time",
-        help="Exponential decay time of the flasher pulse in nanoseconds.",
-        type=float,
-        default=0.0,
-    )
-    flasher_args.add_argument(
-        "--flasher_sig_time",
-        help="Sigma of Gaussian-shaped flasher pulse in nanoseconds.",
-        type=float,
-        default=0.0,
-    )
 
     return config.initialize(
         db_config=True,

simtools/applications/submit_model_parameter_from_external.py

@@ -120,7 +120,6 @@ def main():  # noqa: D103
         parameter_version=args_dict["parameter_version"],
         output_file=Path(args_dict["parameter"] + "-" + args_dict["parameter_version"] + ".json"),
         output_path=output_path,
-        use_plain_output_path=args_dict.get("use_plain_output_path"),
         metadata_input_dict=args_dict,
         db_config=db_config if args_dict.get("check_parameter_version") else None,
     )

simtools/applications/validate_camera_efficiency.py

@@ -129,7 +129,6 @@ def main():  # noqa: D103
         parameter_version=args_dict.get("parameter_version", "0.0.0"),
         output_file=Path(f"nsb_pixel_rate-{args_dict.get('parameter_version', '0.0.0')}.json"),
         output_path=Path(args_dict["output_path"]) / args_dict["telescope"] / "nsb_pixel_rate",
-        use_plain_output_path=args_dict.get("use_plain_output_path"),
     )
 
 

simtools/applications/validate_camera_fov.py

@@ -94,9 +94,8 @@ def main():  # noqa: D103
     logger = logging.getLogger()
     logger.setLevel(gen.get_log_level_from_user(args_dict["log_level"]))
 
-    # Output directory to save files related directly to this app
     _io_handler = io_handler.IOHandler()
-    output_dir = _io_handler.get_output_directory(label, sub_dir="application-plots")
+    output_dir = _io_handler.get_output_directory()
 
     tel_model = TelescopeModel(
         site=args_dict["site"],