Allow to define production grids using a grid density parameter

[GernotMaier]

Improve production_generate_grid.py and plot_production_grid.py for the generation and plotting of production grids along declination lines.

plot_production_grid

Add functionality to generate a grid using a grid density parameter.

Example for ra/dec grid:

    # RA/Dec define the sampling frame; binning placeholders are overridden by
    # direction_grid_density in adaptive RA/Dec mode.
    - ra 0 deg 360 deg 1 linear
    - dec -40 deg 80 deg 1 linear
    - nsb 4 MHz 4 MHz 1 linear
    - offset 0 deg 10 deg 2 linear
    # Explicit local-sky constraints for RA/Dec density filtering.
    local_zenith_range: 0 deg 70 deg
    # Directed azimuth interval (300 -> 60) across wrap-around.
    local_azimuth_range: 300 deg 60 deg
    direction_grid_density: 0.25 1/deg^2

or for horizontal:

    axis:
    - azimuth 0 deg 360 deg 0 linear
    - zenith 0 deg 70 deg 0 linear
    - nsb 4 MHz 5 MHz 2 linear
    - offset 0 deg 10 deg 2 linear
    direction_grid_density: 0.25 1/deg^2

The output tables with the grid include now columns for ra/dec (if applicable) and most of the metadata.

plotting of the grid

plot_production_grid.py has been simplified and reads the table generated with plot_production_grid and plots them. The previously included conversion from alt/az to ra/dec has been removed - as we have now the ra/dec columns in the production grid table.

[Copilot]

Pull request overview

This pull request adds an optional direction grid density parameter for production grid generation (horizontal and RA/Dec), and updates plotting to be file-driven (using precomputed coordinate columns/metadata from the generated grid table rather than doing coordinate conversions during plotting).

Changes:

• Add direction_grid_density parsing and binning derivation to production grid axis resolution (plus optional local-sky constraints for RA/Dec density grids).
• Implement adaptive-density grid generation in ProductionGridEngine (adaptive RA sampling per declination strip; adaptive azimuth sampling per zenith row).
• Simplify production-grid plotting to read and render ECSV tables (including optional RA/Dec panel + metadata subtitle).

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/simtools/production_configuration/angle_ranges.py	New helpers for directed circular spans and tolerant ceiling used by density-based binning.
src/simtools/production_configuration/simulation_jobs.py	Parse/apply direction_grid_density, optional local constraints, and export density metadata.
src/simtools/production_configuration/observation_grid.py	Add adaptive-density grid generation for RA/Dec and horizontal grids; adjust circular binning semantics.
src/simtools/production_configuration/job_grid_io.py	Serialize/deserialize optional RA/Dec columns in job-grid ECSV output.
src/simtools/visualization/plot_production_grid.py	Switch plotting to file-driven normalization and optional RA/Dec panel + metadata subtitle; tracks now disabled.
src/simtools/applications/production_generate_grid.py	Add CLI args/docs for direction_grid_density and local-sky constraints.
src/simtools/applications/plot_production_grid.py	Remove DB/site/time dependencies; now reads grid files directly for plotting.
tests/unit_tests/production_configuration/test_angle_ranges.py	New unit tests for directed-span and tolerant ceiling helpers.
tests/unit_tests/production_configuration/test_simulation_jobs.py	Add unit tests for density parsing, binning derivation, and metadata.
tests/unit_tests/production_configuration/test_observation_grid.py	Add unit tests for adaptive grid generation and directed azimuth handling.
tests/unit_tests/production_configuration/test_job_grid_io.py	Validate optional RA/Dec persistence in serialized job grids.
tests/unit_tests/visualization/test_plot_production_grid.py	Update plot tests for file-driven plotting (no coordinate transforms).
tests/unit_tests/applications/test_production_generate_grid.py	Add CLI parsing tests for --direction_grid_density.
tests/integration_tests/config/production_generate_grid_ra_dec_density.yml	New (skipped) workflow config exercising RA/Dec density settings.
tests/integration_tests/config/production_generate_grid_horizontal_density.yml	New workflow config exercising horizontal density settings.
tests/integration_tests/config/plot_production_grid.yml	Update workflow to match simplified plotting inputs.
docs/source/api-reference/production_configuration.md	Document new production_configuration.angle_ranges module in API reference.
docs/changes/2213.feature.md	Changelog fragment for the new grid-density feature and plotting updates.

Comments suppressed due to low confidence (1)

src/simtools/applications/plot_production_grid.py:22

• plot_ra_dec_tracks / dec_values are documented and advertised as plotting RA/Dec guide tracks, but ProductionGridPlotter.plot_sky_projection() now explicitly disables tracks in file-driven mode (it only logs and ignores the request). The CLI help/docstring should be updated to reflect the current behavior (e.g., deprecate/remove the options, or clearly state they are ignored).

plot_ra_dec_tracks (flag, optional)
    If provided, plot RA/Dec guide tracks on top of the sky projection. When native
    RA/Dec grid points are present (grid file contains explicit ``ra`` and ``dec``
    columns), thin grid lines are inferred automatically.
    Default: False.
dec_values (list of float, optional)
    Optional list of declination values in degrees to plot as manual tracks. If not
    provided, tracks are inferred from native RA/Dec grid points when possible.
    Default: None.

[ctao-sonarqube]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
95.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube