Configure Productions#

Production configuration turns a compact production definition into an executable job grid. Each row of the grid represents one simulation run with a resolved primary particle, model version, array layout, pointing direction, energy range, CORSIKA limits, shower count, and run number. The grid is created with simtools-production-generate-grid.

Warning

Production configuration is a policy-heavy step, with many parameter choices defined by the user. Small changes to pointing coverage, event statistics, CORSIKA limits, or energy scaling can multiply the number of generated jobs or change the simulated phase space. A review of the generated grid is required before submission.

Configuration Workflow#

The production context includes:

  • the site, model version, and array layout;

  • the primary particles, CORSIKA interaction models, and hadronic transition energy;

  • the simulation energy range, core scatter, and view cone;

  • whether the pointing grid is horizontal (azimuth/zenith) or hour-angle (ha/dec);

  • the source-offset grid points;

  • the model version, which determines the NSB rate used by the production grid;

  • whether the number of runs is fixed or derived from a total shower target;

  • whether direction-dependent CORSIKA limits or zenith-dependent scaling should be applied.

The CORSIKA and sim_telarray executable versions are not selected directly in the grid. They are determined by the production environment, usually the container image used for execution. The exact software versions used by a production are identified from the image tag, image release notes, and generated run logs.

Some parameters are normally production-policy settings rather than per-production tuning knobs. Examples are simulation_software, curved_atmosphere_min_zenith_angle, and corsika_hadronic_transition_energy. An explicitly configured transition energy is written into every job-grid row; when omitted, the transition field is omitted and the selected CORSIKA executable retains its own behavior.

Pointing Strategy#

Pointing directions and other grid dimensions are configured with axis entries. A production grid always needs direction axes plus the non-direction axes used by the simulation, usually offset.

NSB is not a grid axis. simtools resolves the integrated NSB rate from the site model for each selected model_version and writes it to the job grid as nsb_rate. This means that NSB values are directly dependent on the model version. When a production requests several model versions, the same pointing and offset grid can result in different nsb_rate values for each version.

A horizontal grid is used when the production is defined directly in local coordinates. This is the usual choice for simulations binned by zenith and azimuth:

axis:
- azimuth 310 deg 20 deg 3 linear
- zenith 30 deg 40 deg 2 linear
- offset 0 deg 0 deg 1 linear

This example defines a horizontal grid with evenly spaced bins between the listed minimum and maximum azimuth and zenith values, plus a single offset point.

Directed azimuth ranges may cross the 0 deg boundary. For example, 310 deg to 20 deg covers the interval through North.

An hour-angle grid is used when the production is defined by local hour angle and declination. simtools converts each HA/Dec point to local azimuth and zenith using the site latitude, because CORSIKA and sim_telarray still need local horizontal coordinates:

axis:
- ha 0 deg 360 deg 36 linear
- dec -90 deg 90 deg 18 linear
- offset 0 deg 10 deg 2 linear

For either coordinate system, direction_grid_density can be used instead of an explicit number of direction bins. The axis ranges still define the accepted domain, while simtools derives the number of direction points from the requested density. This is useful when the grid is intended to sample solid angle more uniformly or follow the interpolation scale of CORSIKA limits:

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

For density-based HA/Dec grids, local-sky filters restrict the generated points to the observable region needed for the production:

axis:
- ha 0 deg 360 deg 1 linear
- dec -40 deg 80 deg 1 linear
- offset 0 deg 10 deg 2 linear
direction_grid_density: 0.25 1/deg^2
local_zenith_range: 0 deg 70 deg
local_azimuth_range: 300 deg 60 deg

Energy and CORSIKA Limits#

energy_range, core_scatter, and view_cone define the requested simulation phase space. Fixed energies can be simulated by setting the minimum and maximum energy to the same value. Multiple fixed energies or energy bins can be provided as a list of energy-range pairs in a configuration file.

If a CORSIKA limits table is passed through corsika_limits, simtools interpolates the table for each direction point using zenith, azimuth, and the model-version-dependent nsb_rate. The configured values remain absolute bounds: lookup thresholds can tighten the selected energy range, core scatter, or view cone, but they do not expand beyond the configured limits.

This separation is important for production reviews:

  • the configuration expresses the intended maximum phase space;

  • the lookup table expresses what is valid for a given direction, NSB rate, and array layout;

  • the generated grid shows the final values that will be executed.

The CORSIKA-limit workflow described in the pre-requisites documentation applies when the production depends on lookup-table limits.

Event Statistics#

Production statistics can be configured in two common ways:

  • number_of_runs and showers_per_run when the number of jobs per grid point is fixed;

  • total_showers and showers_per_run when the number of jobs should be derived from a physics-motivated total shower target.

The second mode rounds up the number of runs when the requested total is not divisible by the selected showers per run, so all runs at a grid point have the same shower count.

For fixed-energy or wide-zenith productions, the grid generator also supports energy- and zenith-dependent scaling of showers per run, total showers, and maximum energy. The exact formulae and parameter names are documented in the simtools-production-generate-grid reference.

Example Configuration#

The following compact configuration generates a horizontal gamma-production grid with CORSIKA limits and a fixed number of runs per grid point:

axis:
- azimuth 310 deg 20 deg 3 linear
- zenith 30 deg 40 deg 2 linear
- offset 0 deg 0 deg 1 linear
primary: gamma
model_version: 7.0.0
array_layout_name: LSTN-01
corsika_le_interaction: urqmd
corsika_he_interaction: epos
corsika_hadronic_transition_energy: 80 GeV
energy_range: 30 GeV 300 GeV
core_scatter: 10 500 m
view_cone: 0 deg 10 deg
showers_per_run: 5
number_of_runs: 2
corsika_limits: tests/resources/corsika_simulation_limits/corsika_limits_north.ecsv
output_file: job_grid_horizontal.ecsv

Grid generation command:

simtools-production-generate-grid --config path/to/production_generate_grid.yml

Several integration-test configurations are useful starting points:

  • tests/integration_tests/config/production_generate_grid_horizontal.yml

  • tests/integration_tests/config/production_generate_grid_ha_dec.yml

Production Grid Plotting#

The output is an ECSV production grid. Each row describes one executable run, including primary, pointing, energy range, core scatter settings, view cone, showers per run, model version, model-version-dependent nsb_rate, array layout, interaction models, and run number.

The generated table is inspected before job submission. The review includes:

  • the number of rows and run numbers;

  • the final energy ranges after lookup limits and scaling;

  • the final core-scatter and view-cone values;

  • the nsb_rate values for each model version;

  • the direction coverage and any skipped grid points.

simtools-plot-production-grid visualizes the sky coverage:

simtools-plot-production-grid \
    --grid_points_file tests/resources/production_job_grid_horizontal.ecsv \
    --output_path simtools-output