simtools-simulate-illuminator#

Simulate illuminator (distant calibration light source).

Illuminators are calibration light sources not attached to a particular telescope. Three modes of operation are supported:

Single pair: simulate one illuminator-telescope pair with positions from the model repository.
Single pair with configurable position: override the illuminator position and pointing.
Multi-pair: simulate all valid illuminator-telescope pairs from the visibility table in parallel, using a configurable number of CPU cores.

Example Usage

Simulate illuminator with positions as defined in the simulation-model repository:

simtools-simulate-illuminator --light_source ILLN-01 \
--telescope MSTN-04 --site North \
--model_version 7.0.0

Simulate at a configurable position (1km above array center) and pointing downwards:
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 7.0.0
An explicit source position together with downward pointing (0, 0, -1) places the telescope at the array origin. Other setups use the model telescope position. Both backends use the model’s telescope_sphere_radius.

Simulate all valid pairs from the visibility table in parallel:

simtools-simulate-illuminator --site North \
--model_version 7.0.0 --simulate_all

Simulate all pairs for a specific illuminator only:

simtools-simulate-illuminator --site North \
--model_version 7.0.0 --simulate_all \
--light_source ILLN-01

Simulate all pairs with explicit worker count:

simtools-simulate-illuminator --site North \
--model_version 7.0.0 --simulate_all \
--max_workers 8

Simulate with a specific wavelength (e.g., 355 nm):

simtools-simulate-illuminator --light_source ILLN-01 \
--telescope MSTN-04 --site North \
--model_version 7.0.0 --wavelength 355 nm

Simulate with multiple wavelengths:

simtools-simulate-illuminator --light_source ILLN-01 \
--telescope MSTN-04 --site North \
--model_version 7.0.0 --wavelength 355 nm 473 nm

Simulate all pairs for all wavelengths in model (no wavelength specified):

simtools-simulate-illuminator --site North \
--model_version 7.0.0 --simulate_all

Using a config file with specific wavelengths:

Create a config file (e.g., illuminator_config.yml):

site: North
model_version: 7.0.0
light_source: ILLN-01
telescope: MSTN-04
wavelength: [355, 473]

Then run:

simtools-simulate-illuminator --config illuminator_config.yml

Command Line Arguments

light_source (str, optional): Illuminator in array, e.g., ILLN-01. Required for single-pair mode. In multi-pair mode, used as a filter (simulate only pairs with this illuminator).
number_of_events (int, optional): Number of events to simulate.
flasher_photons (int, optional): Overwrite the model parameter flasher_photons.
wavelength (float or list of float, optional): Wavelength(s) in nanometers (unitless values are interpreted as nm). Must be one of the wavelengths supported by the illuminator model. Multiple wavelengths can be specified (space-separated on command line, or as a list in config file: wavelength: [355, 473]). If not specified, all model wavelengths will be simulated Each wavelength will be validated and simulated as a separate job.
telescope (str, optional): Telescope model name (e.g. LSTN-01, MSTN-04, …). Required for single-pair mode. In multi-pair mode, used as a filter (simulate only pairs with this telescope).
site (str, required): Site name (North or South).
model_version (str, optional): Version of the simulation model.
simulate_all (flag, optional): Simulate all valid illuminator-telescope pairs from the visibility table.
max_workers (int, optional): Maximum number of parallel workers for multi-pair mode. Default: 60% of CPU cores. Set to 0 to use all available cores.
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.

Command line arguments#

options#

–help

show this help message and exit

–light_source

Illuminator name, e.g. ILLN-01. Required for single-pair mode.

–simulate_all

Simulate all valid illuminator-telescope pairs from the visibility table.

–number_of_events

Number of events to simulate

Default: 1.

–flasher_photons

Override flasher photon yield. Accepts integers including scientific notation, e.g. 1e8.

–wavelength

Wavelength(s) in nanometers (unitless values are interpreted as nm). Values must be supported by the illuminator model (typically 266, 355, 473, or 532 nm). Specify multiple values space-separated on the command line or as a list in configuration. If omitted, simulate all model wavelengths.

Configurable light source position and pointing (override simulation model values)#

–light_source_position: Light source position (x,y,z) relative to the array center (ground coordinates) in m
–light_source_pointing: Light source pointing direction (example pointing downwards: –light_source_pointing 0 0 -1)

simulation model#

–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.
–telescope: telescope model name (e.g., LSTN-01, SSTS-design, …)

simulation configuration#

–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).
–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#

Simulate a positioned North illuminator#

Ray-trace a calibration illuminator from a user-defined position and pointing direction to MSTN-02.

Application: simtools-simulate-illuminator

Integration test: simulate_illuminator_configurable_position.yml

Command

simtools-simulate-illuminator --config tests/integration_tests/config/simulate_illuminator_configurable_position.yml

Configuration

light_source: ILLN-01
light_source_position:
- 0.0
- 0.0
- 1000.0
light_source_pointing:
- 0.0
- 0.0
- -1.0
model_version: 7.0.0
output_path: simtools-output/illuminator-variable
site: North
telescope: MSTN-02
flasher_photons: 1e9
log_level: DEBUG

Simulate the North illuminator layout#

Use the modelled ILLN-01 position and orientation to ray-trace calibration light to MSTN-02.

Application: simtools-simulate-illuminator

Integration test: simulate_illuminator_layout.yml

Command

simtools-simulate-illuminator --config tests/integration_tests/config/simulate_illuminator_layout.yml

Configuration

light_source: ILLN-01
model_version: 7.0.0
output_path: simtools-output
site: North
telescope: MSTN-02
flasher_photons: 1e9
log_level: DEBUG

Simulate an illuminator for all North telescopes#

Generate 300 nm calibration-light events for every telescope illuminated by the North-site source.

Application: simtools-simulate-illuminator

Integration test: simulate_illuminator_multi.yml

Command

simtools-simulate-illuminator --config tests/integration_tests/config/simulate_illuminator_multi.yml

Configuration

model_version: 7.0.0
output_path: simtools-output
site: North
simulate_all: true
light_source: ILLN-01
flasher_photons: 1e8
wavelength: 300
log_level: DEBUG