simtools-plot-array-layout#

Plot array elements (array layouts).

Plot array layouts in ground or UTM coordinate systems from multiple sources.

For the following options, array element positions are retrieved from the simulation-model repository:

from the simulation-model repository using the layout name (e.g., -array_layout_name alpha)
from the model parameter data, retrieving all layouts for the given site and model version (--plot_all_layouts)
from a model parameter file (e.g., -array_layout_parameter_file tests/resources/model_parameters/array_layouts-2.0.2.json)
from a list of array elements (e.g., -array_element_list MSTN-01, MSTN-02). Positions are retrieved from the model repository. * explicit listing: e.g., -array_element_list MSTN-01, MSTN05 * listing of types: e.g, -array_element_list MSTN plots all telescopes of type MSTN.

For this option, array element positions are retrieved from the input file:

from a file containing an astropy table with a list of array elements and their positions (e.g., -array_layout_file tests/resources/telescope_positions-North-ground.ecsv)

Plots are saved as png files in the output directory by default.

Example of a layout plot:

../../_images/plot_array_layout_example.png

Command line arguments

figure_namestr: File name for the output figure.
array_layout_filestr: File (astropy table compatible) with a list of array elements.
array_layout_namestr: Name of the layout array (e.g., test_layout, alpha, 4mst, etc.). Use ‘plot_all’ to plot all layouts from the model repository for the given site and model version.
array_layout_parameter_filestr, optional: File with array layouts similar in the model parameter file format (typically JSON).
array_layout_name_from_parameter_filelist, optional: Name(s) of the array layout(s) to plot from array_layout_parameter_file.
array_layout_name_background: str, optional: Name of the background layout array (e.g., test_layout, alpha, 4mst, etc.).
array_element_listlist: List of array elements (e.g., telescopes) to plot (e.g., LSTN-01 LSTN-02 MSTN).
coordinate_systemstr, optional: Coordinate system for the array layout (ground or utm).
show_labelsbool, optional: Shows the telescope labels in the plot.
axes_rangefloat, optional: Range of the both axes in meters.
marker_scalingfloat, optional.: Scaling factor for plotting of array elements, optional.
grayed_out_array_elementslist, optional: List of array elements to plot as gray circles.
highlighted_array_elementslist, optional: List of array elements to plot with red circles around them.
legend_locationstr, optional: Location of the legend (default “best”).
boundsstr, optional: Axis bounds mode. Use “symmetric” for +-R with padding (default) or “exact” for per-axis min/max bounds.
paddingfloat, optional: Fractional padding applied around computed extents in both modes (default 0.1).
x_limtuple(float, float), optional: Explicit x-axis limits [xmin, xmax] in meters. When provided, overrides derived limits and filters plotted elements by x.
y_limtuple(float, float), optional: Explicit y-axis limits [ymin, ymax] in meters. When provided, overrides derived limits and filters plotted elements by y.

Examples

Plot “alpha” layout for the North site with model version 6.0.0:

simtools-plot-array-layout --site North
                           --array_layout_name alpha
                           --model_version=6.0.0

Plot layout with 2 LSTs on top of north alpha layout:

simtools-plot-array-layout --site North
                           --array_element_list LSTN-01,LSTN-02
                           --model_version=6.0.0
                           --array_layout_name_background alpha

Plot layout from a file with a list of telescopes:

simtools-plot-array-layout
    --array_layout_file tests/resources/telescope_positions-North-ground.ecsv

Use exact bounds with default padding:

simtools-plot-array-layout --array_layout_name alpha         --site North --model_version 6.0.0 --bounds exact

Use symmetric bounds with custom padding:

simtools-plot-array-layout --array_layout_name alpha         --site North --model_version 6.0.0 --bounds symmetric --padding 0.15

Plot layout from a parameter file with a list of telescopes:

simtools-plot-array-layout
    --array_layout_parameter_file tests/resources/model_parameters/array_layouts-2.0.2.json
    --model_version 6.0.0

Plot one layout from a parameter file:

simtools-plot-array-layout
    --array_layout_parameter_file tests/resources/model_parameters/array_layouts-2.0.2.json
    --array_layout_name_from_parameter_file alpha
    --model_version 6.0.0

Plot all layouts for the North site and model version 6.0.0:

simtools-plot-array-layout --site North --plot_all_layouts --model_version=6.0.0

Plot layout with some telescopes grayed out and others highlighted:

simtools-plot-array-layout --site North
                           --array_layout_name alpha
                           --model_version=6.0.0
                           --grayed_out_array_elements LSTN-01 LSTN-02
                           --highlighted_array_elements MSTN-01 MSTN-02
                           --legend_location "upper right"

Command line arguments#

options#

–help

show this help message and exit

–all_sites

Plot layouts for all sites.

–figure_name

Name of the output figure to be saved.

–show_labels

Plot array element labels.

–marker_scaling

Scaling factor for the markers.

Default: 1.0.

–coordinate_system

Coordinate system for the array layout.

Default: ground. Choices: ground, utm.

–axes_range

Range of the both axes in meters.

–x_lim

Explicit x-axis limits [xmin xmax] in meters.

–y_lim

Explicit y-axis limits [ymin ymax] in meters.

–array_layout_name_background

Name of the background layout array (e.g., test_layout, alpha, 4mst, etc.).

–grayed_out_array_elements

List of array elements to plot as gray circles.

–highlighted_array_elements

List of array elements to plot with red circles around them.

–legend_location

Legend location: ‘best’, ‘upper right’, ‘upper left’, ‘lower left’, ‘lower right’, ‘right’, ‘center left’, ‘center right’, ‘lower center’, ‘upper center’, ‘center’, or ‘no_legend’.

Default: best.

–bounds

Axis bounds mode: ‘symmetric’ uses +-R with padding, ‘exact’ uses per-axis min/max

Default: symmetric. Choices: symmetric, exact.

–padding

Fractional padding applied around computed extents (used for both modes).

Default: 0.1.

application#

–all_model_versions: Produce reports for all model versions.
–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.
–overwrite_model_parameters: JSON string with model parameters to overwrite
–ignore_missing_design_model: Ignore missing design model definition of model repository
–site: Observatory site (e.g., North, South). Use –show_options site.
–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.
–array_element_list: list of array elements (e.g., LSTN-01, LSTN-02, MSTN).
–array_layout_file: file(s) with the list of array elements (astropy table format).
–array_layout_parameter_file: Array layout model parameter file (typically in JSON format).
–plot_all_layouts: plot all available layouts
–array_layout_name_from_parameter_file: Array layout name(s) to plot from an array layout parameter file.

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.

Examples#

Plot a named North LST layout#

Resolve a versioned North LST subarray by name and plot its telescope positions as PDF and PNG.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_by_name.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_by_name.yml

Configuration

array_layout_name:
  by_version:
    <7.0.0: subsystem_lsts
    '>=7.0.0': CTAO-North-LSTs
figure_format:
- pdf
- png
model_version: 6.0.2
output_path: simtools-output
site: North

Plot layouts from a model-parameter file#

Read array-layout definitions from JSON and plot the contained telescope configurations.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_from_array_layouts_json.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_from_array_layouts_json.yml

Configuration

array_layout_parameter_file: ${prepared:array_layouts-2.0.2.json}
figure_format:
- pdf
- png
model_version: 6.0.2
output_path: simtools-output

Plot a South layout in UTM coordinates#

Plot UTM positions of selected South-site LST, MST, and SST elements.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_from_list_utm_south.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_from_list_utm_south.yml

Configuration

array_element_list:
- LSTS
- MSTS
- SSTS
coordinate_system: utm
figure_format:
- pdf
- png
model_version: 6.0.2
output_path: simtools-output

Plot a layout from one position file#

Read a North-site ground-position table and plot its telescope layout as PDF and PNG.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_one_file.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_one_file.yml

Configuration

array_layout_file: ${static:telescope_positions-North-ground.ecsv}
figure_format:
- pdf
- png
output_path: simtools-output

Plot a named layout from one position file#

Read a North-site ground-position table and write the layout plot with an explicit figure name.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_one_file_with_name.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_one_file_with_name.yml

Configuration

array_layout_file: tests/resources/static/telescope_positions-North-ground.ecsv
figure_format:
- pdf
- png
figure_name: test
output_path: simtools-output

Compare North and South array layouts#

Read two ground-position tables and plot the North and South telescope layouts together.

Application: simtools-plot-array-layout

Integration test: plot_array_layout_two_files.yml

Command

simtools-plot-array-layout --config tests/integration_tests/config/plot_array_layout_two_files.yml

Configuration

array_layout_file:
- ${static:telescope_positions-North-ground.ecsv}
- ${static:telescope_positions-South-ground.ecsv}
figure_format:
- pdf
- png
output_path: simtools-output