simtools-simulate-flasher

Simulate flasher devices used e.g. for camera flat fielding.

The flasher simulation allows for two different run modes:

1. Direct injection of light into the camera (bypassing the telescope optics).

2. Simulation of light emission from the source using the light-emission package from sim_telarray.

Full-simulation flat-fielding uses the source geometry and angular distribution to illuminate the camera, but sets Bypass_Optics=1 in sim_telarray, bypassing telescope optics in this case. Both modes produce sim_telarray events for standard analysis or visualization with ‘simtools-plot-simtel-events’.

Photon counts and matching run modes

The flasher_photons setting has a different meaning in each run mode:

Photon count meanings by run mode

Run mode	Meaning of flasher_photons
direct_injection	Overrides the model parameter flasher_photons_at_pixel, setting the injected photon count per pixel.
full_simulation	Sets the number of photons emitted by the flasher source and passed to sim_telarray.

For a matched comparison, determine the expected camera illumination for the chosen source, wavelength, pulse, and telescope, then derive the direct per-pixel setting. Validate it with signal distributions and a separate per-pixel mean and variance analysis; the comparison below summarizes signals across pixels and events.

Comparing signal outputs

Compare the sim_telarray files with simtools-compare-productions in signal mode. Quote file patterns so the application can expand them:

simtools-compare-productions \
    --comparison_level signal \
    --production direct_injection "/path/to/direct/*.simtel.zst" \
    --production full_simulation "/path/to/full/*.simtel.zst" \
    --telescope_name LSTN-01 \
    --output_path flasher-comparison

The signals.png plot compares integrated-signal distributions across pixels and events. Its legend identifies productions only; it does not display means or match pixels between files. For mean-based scaling, use simtools.production_configuration.comparison.collect_signal_metrics and calculate metrics.signals.mean() for each returned production metric, grouped by telescope. See simtools-compare-productions for comparison options and outputs.

Example Usage

1. Simulate a single telescope:

   simtools-simulate-flasher --run_mode full_simulation \
   --light_source_type flat_fielding --model_version 7.0.0 \
   --site North --telescopes MSTN-04 --run_number 10
   

2. Simulate several telescopes:

   simtools-simulate-flasher --run_mode full_simulation \
   --light_source_type flat_fielding --model_version 7.0.0 \
   --site North --telescopes MSTN-04 MSTN-05 --run_number 10
   

3. Simulate all telescopes from an array layout:

   simtools-simulate-flasher --run_mode full_simulation \
   --light_source_type flat_fielding --model_version 7.0.0 \
   --site North --array_layout_name alpha --run_number 10
   

4. Simulate flashers for direct injection:

   simtools-simulate-flasher --run_mode direct_injection \
   --light_source MSFx-FlashCam --model_version 7.0.0 \
   --array_layout_name subsystem_msts --site South \
   --run_number 3
   

Command Line Arguments

run_mode (str, required)

Run mode, either “direct_injection” or “full_simulation”.

telescopes (str, optional)

One or more telescope names (e.g. LSTN-01, MSTN-04, SSTS-04, …). Use for single-telescope or multi-telescope simulations.

array_layout_name (str, optional)

Name of the array layout. In full-simulation mode, all telescopes from this layout are simulated (one run per telescope).

site (str, required)

Site name (North or South).

light_source (str, optional)

Explicit calibration light source model, e.g. MSFx-FlashCam.

light_source_type (str, optional)

Light source type, e.g. flat_fielding. Recommended for array-style simulations because the corresponding flasher model is read from the simulation-model repository for each telescope.

number_of_events (int, optional):

Number of events to simulate (default: 1). Can be a single value or a list.

flasher_photons (int, optional)

Photon intensity; its meaning depends on the run mode as described above. Can be a single value or a list for filter wheel sequences.

model_version (str, optional)

Version of the simulation model.

run_number (int, optional)

Run number to use (default: 1, required for direct injection mode).

Command line arguments

options

–help

show this help message and exit

–run_mode

Flasher simulation run mode

Required. Choices: direct_injection, full_simulation.

–light_source

Flasher device associated with a specific telescope, i.e. MSFx-FlashCam

–light_source_type

Type of the light source (e.g. flat_fielding)

–number_of_events

Number of flasher events to simulate

Default: 1.

–flasher_photons

Override flasher photon yield (one value for all telescopes). Accepts integers including scientific notation, e.g. 1e6.

simulation model

–telescopes

list of telescopes (e.g., LSTN-01, SSTS-design, …)

–array_layout_name

Array layout name(s) (e.g., CTAO-North-Alpha, LSTN-01). Telescope names are assumed as single-telescope layouts. Use –show_options array_layout_name.

–model_version

Simulation production model version(s). Use –show_options model_version.

–overwrite_model_parameters

JSON string with model parameters to overwrite

–site

Observatory site (e.g., North, South). Use –show_options site.

simulation configuration

–run_number

Run number to be simulated.

Default: 1.

–instrument_seed

Seed of the random instrument setup (e.g. mirror deviations, gains); with several random instrument instances, their seeds are derived from it (default: random).

–random_instrument_instances

Number of random instrument instances (e.g. random mirror realisations).

Default: 1.

–simulation_seed

Seed of the simulation (events, photons) (default: random). Two values: [instrument_seed, simulation_seed] (use for testing only).

ray tracing configuration

–ray_tracing_backend

Optical ray-tracing backend (default: sim_telarray).

Choices: sim_telarray, obdeect.

model repository

–simulation_models_path

Path containing the simulation-model repository to read.

–simulation_models_git_path

Path to a local normal, bare, or mirror Git repository containing simulation models.

–simulation_models_git_revision

Git tag, ref, or commit to read from the simulation-model repository.

application

–show_options

Print available values for a supported option and exit.

Examples

Inject flasher signals into North cameras

Generate flat-fielding events by injecting calibration signals directly into North-site LST and MST cameras.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_direct_injection_lst_north.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_direct_injection_lst_north.yml

Configuration

run_mode: direct_injection
telescopes:
- LSTN-01
- MSTN-03
label: test-flasher-direct-injection-lst-north
light_source_type: flat_fielding
log_level: DEBUG
model_version: 7.0.0
number_of_events: 3
output_path: simtools-output
run_number: 10
random_instrument_instances: 100
site: North

Inject an LST filter-wheel intensity sequence

Generate North-LST camera calibration events at two photon intensities by direct signal injection.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_direct_injection_lst_north_filter_wheel.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_direct_injection_lst_north_filter_wheel.yml

Configuration

run_mode: direct_injection
light_source_type: flat_fielding
telescopes:
- LSTN-01
label: test-flasher-direct-injection-lst-north-filter-wheel
log_level: DEBUG
model_version: 7.0.0
number_of_events:
- 2
- 1
flasher_photons:
- 1e6
- 2e6
output_path: simtools-output
run_number: 10
random_instrument_instances: 100
site: North

Inject flasher signals into a South LST

Generate calibration events by injecting an LSFS light-source signal directly into a South-site LST camera.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_direct_injection_lst_south.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_direct_injection_lst_south.yml

Configuration

run_mode: direct_injection
light_source: LSFS-design
array_layout_name: LSTS-02
label: test-flasher-direct-injection-lst-south
log_level: DEBUG
model_version: 7.0.0
number_of_events: 3
output_path: simtools-output
run_number: 10
random_instrument_instances: 100
site: South

Inject flasher signals into a South FlashCam

Generate calibration events by injecting an MSFx-FlashCam signal directly into South MST cameras.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_direct_injection_mst_flashcam.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_direct_injection_mst_flashcam.yml

Configuration

run_mode: direct_injection
light_source: MSFx-FlashCam
array_layout_name: subsystem_msts
label: test-flasher-direct-injection-south
log_level: DEBUG
model_version: 7.0.0
number_of_events: 3
output_path: simtools-output
run_number: 10
random_instrument_instances: 100
site: South

Inject flasher signals into a North NectarCam

Generate calibration events by injecting an MSFx-NectarCam signal directly into a North MST camera.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_direct_injection_mst_nectarcam.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_direct_injection_mst_nectarcam.yml

Configuration

run_mode: direct_injection
light_source: MSFx-NectarCam
array_layout_name: MSTN-03
label: test-flasher-direct-injection-mst-nectarcam
log_level: DEBUG
model_version: 7.0.0
number_of_events: 3
output_path: simtools-output
run_number: 10
random_instrument_instances: 100
site: North

Simulate a flasher for a North subarray

Propagate flat-fielding light through the optics and cameras of a North layout containing LSTs and an MST.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_alpha_north.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_alpha_north.yml

Configuration

run_mode: full_simulation
light_source_type: flat_fielding
model_version: 7.0.0
output_path: simtools-output
site: North
array_layout_name: CTAO-North-4-LSTs-1-MSTs
run_number: 10
flasher_photons: 1e6
log_level: DEBUG

Simulate an LST filter-wheel intensity sequence

Propagate two LSFS photon intensities through a South LST optics and camera model.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_lst_filter_wheel.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_lst_filter_wheel.yml

Configuration

run_mode: full_simulation
light_source: LSFS-design
model_version: 7.0.0
output_path: simtools-output
site: South
telescopes:
- LSTS-01
run_number: 10
number_of_events:
- 5
- 2
flasher_photons:
- 1e6
- 2e6
log_level: DEBUG

Simulate LST flashes with a shared event count

Propagate two flat-fielding intensities through a South LST using the same event count for each setting.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_lst_filter_wheel_single_event_value.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_lst_filter_wheel_single_event_value.yml

Configuration

run_mode: full_simulation
light_source_type: flat_fielding
model_version: 7.0.0
output_path: simtools-output
site: South
telescopes:
- LSTS-01
run_number: 20
number_of_events: 2
flasher_photons:
- 1e6
- 2e6
log_level: DEBUG

Simulate an LSFS flash for a South LST

Propagate an LSFS calibration pulse through the optics and camera of LSTS-04.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_lst_south.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_lst_south.yml

Configuration

run_mode: full_simulation
light_source: LSFS-design
model_version: 7.0.0
output_path: simtools-output
site: South
telescopes: LSTS-04
run_number: 10
flasher_photons: 1e6
log_level: DEBUG

Simulate an MSFx flash for a South FlashCam

Propagate an MSFx calibration pulse through the optics and FlashCam camera of MSTS-04.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_mst_flashcam.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_mst_flashcam.yml

Configuration

run_mode: full_simulation
light_source: MSFx-FlashCam
model_version: 7.0.0
output_path: simtools-output
site: South
telescopes: MSTS-04
run_number: 10
flasher_photons: 1e6
log_level: DEBUG

Simulate an MSFx flash for a North NectarCam

Propagate an MSFx calibration pulse through the optics and NectarCam camera of MSTN-04.

Application: simtools-simulate-flasher

Integration test: simulate_flasher_full_simulation_mst_nectarcam.yml

Command

simtools-simulate-flasher --config tests/integration_tests/config/simulate_flasher_full_simulation_mst_nectarcam.yml

Configuration

run_mode: full_simulation
light_source: MSFx-NectarCam
model_version: 7.0.0
output_path: simtools-output
site: North
telescopes: MSTN-04
run_number: 10
flasher_photons: 1e6
log_level: DEBUG