simtools-validate-optics#

Validate the optical model through ray tracing simulations of the whole telescope.

Validation type optics (default) scans field angles and derives the PSF (D80), effective mirror area and effective focal length. Validation type cumulative_psf compares the simulated cumulative PSF with measured PSF data (--data).

A point-like light source is assumed. The output includes PSF (D80), effective mirror area and effective focal length as a function of the off-axis angle.

The telescope zenith angle and the source distance can be set by command line arguments.

Examples of the plots generated by this application are shown below. On the top, the D80 vs off-axis is shown in cm (left) and deg (right). On the bottom, the effective mirror area (left) and the effective focal length (right) vs off-axis angle are shown.

../../_images/validate_optics_North-LST-1_d80_cm.png

../../_images/validate_optics_North-LST-1_d80_deg.png

../../_images/validate_optics_North-LST-1_eff_area.png

../../_images/validate_optics_North-LST-1_eff_flen.png

Command line arguments

type (str, optional): Validation type: ‘optics’ (default; field-angle scan of the whole telescope) or ‘cumulative_psf’ (cumulative PSF compared with measured data given by ‘–data’).
data (str, required for type cumulative_psf): Measured cumulative PSF data file.
site (str, required): North or South.
telescope (str, required): Telescope model name (e.g. LST-1, SST-D, …).
model_version (str, optional): Model version.
parameter_version (str, optional): Parameter version for exporting effective_focal_length as model parameter json.
source_distance (float or quantity, optional): Source distance in km.
zenith_angle (float or quantity, optional): Zenith angle in deg.
max_offset (float or quantity, optional): Maximum offset angle in deg.
offset_step (float or quantity, optional): Offset angle step size.
plot_images (activation mode, optional): Produce a multiple pages pdf file with the image plots.
save_photons (activation mode, optional): Retain compressed photon list files after analysis.
test (activation mode, optional): If activated, application will be faster by simulating fewer photons.

Example

LST-1 5.0.0

simtools-validate-optics --site North --telescope LST-1 --max_offset 1.0 \\
--zenith_angle 20 --source_distance 10 --test \\
--model_version 6.0.1 --parameter_version 0.0.0

The output is saved in simtools-output/validate_optics

Compare the cumulative PSF with measured data (type cumulative_psf):

simtools-validate-optics --type cumulative_psf --site North --telescope LST-1 \\
--zenith_angle 20 --data PSFcurve_data_v2.ecsv --model_version 6.0.2

Expected final print-out message:

INFO::ray_tracing(l434)::plot::Plotting eff_area vs off-axis angle
INFO::ray_tracing(l434)::plot::Plotting eff_flen vs off-axis angle

Command line arguments#

options#

–help

show this help message and exit

–type

Validation type: optics (field-angle scan) or cumulative_psf (measured PSF comparison).

Default: optics. Choices: optics, cumulative_psf.

–number_of_photons

Total photons per offset; omitted values retain backend sampling defaults.

–max_workers

Maximum concurrent ray-tracing simulations (positive integer).

Default: 8.

–offset_file

Path to ECSV file with x, y offset columns (in degrees). If provided, overrides max_offset and offset_step.

–offset_directions

Cardinal directions for offset generation (comma-separated): N,S,E,W. Only used with max_offset. Default: all four directions.

Default: N,S,E,W.

–plot_images

Produce a multiple pages pdf file with the image plots.

–plot_images_in_degrees

When plotting PSF images, convert X/Y positions from cm to degrees using the effective focal length. Requires –plot_images.

–save_photons

Retain compressed photon list files after analysis.

application#

–data

Measured cumulative PSF data file (required for type cumulative_psf).

–source_distance

Source distance in km (unitless values are interpreted as km).

Default: 10.0 km.

–zenith_angle

Zenith angle in degrees (between 0 and 180).

Default: 20.0 deg.

–max_offset

Maximum offset angle in degrees (unitless values are interpreted as deg).

Default: 4.0 deg.

–offset_step

Offset angle step size in degrees (unitless values are interpreted as deg).

Default: 0.25 deg.

–show_options

Print available values for a supported option and exit.

simulation model#

–model_version: Simulation production model version(s). Use –show_options model_version.
–parameter_version: model parameter 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, …)

ray tracing configuration#

–ray_tracing_backend

Optical ray-tracing backend (default: sim_telarray).

Choices: sim_telarray, obdeect.

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

–random_instrument_instances

Number of random instrument instances (random mirror realisations) per image.

Default: 20.

–simulation_seed

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

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.

Example#

Validate the LST optical model#

Ray-trace an LST across field angles and compare effective focal length and PSF quantities with reference data.

Application: simtools-validate-optics

Integration test: validate_optics_run.yml

Command

simtools-validate-optics --config tests/integration_tests/config/validate_optics_run.yml

Configuration

max_offset: 1.5
offset_step: 0.5
model_version: 6.0.2
output_path: simtools-output
site: North
source_distance: 11.0
telescope: LSTN-01
test: true
zenith_angle: 20
plot_images: true

Validate the cumulative LST point-spread function#

Compare ray-traced LST containment radii at 20 deg zenith angle with measured PSF data.

Application: simtools-validate-optics

Integration test: validate_optics_cumulative_psf_prod6_psf.yml

Command

simtools-validate-optics --config tests/integration_tests/config/validate_optics_cumulative_psf_prod6_psf.yml

Configuration

type: cumulative_psf
data: ${downloaded:PSFcurve_data_v2.ecsv}
model_version: 6.0.2
output_path: simtools-output
site: North
telescope: LSTN-01
test: true
zenith_angle: 20