simtools-generate-bias-curve-submissions#

Generate scan grids for NSB and proton telescope trigger bias curves.

This application always prepares both curves:

NSB curve
Proton curve with proton primary

For each curve, the application creates a production grid and parameter-scan grid:

base_grid.ecsv
scan_config.yaml
scan_grid.ecsv

The resulting scan grids can be consumed by a backend-specific submission generator, for example simtools-simulate-prod-htcondor-generator.

Command line arguments

site (str, required): Observation site (e.g., North, South).
model_version (str, required): Simulation model version.
array_layout_name (str, required): Single-telescope array layout name for simulations.
simulation_software (str): Simulation software (default: corsika_sim_telarray).
azimuth_angle (float, required): Azimuth angle in degrees.
zenith_angle (float, required): Zenith angle in degrees.
showers_per_run (int, required): Number of showers per run.
core_scatter (str, required): Core scatter (e.g., “20 1900 m”).
view_cone (str, required): View cone (e.g., “0 deg 5 deg”).
number_of_runs (int, required): Number of runs.
corsika_le_interaction (str): CORSIKA low-energy interaction model (default: urqmd).
corsika_he_interaction (str): CORSIKA high-energy interaction model (default: epos).
corsika_hadronic_transition_energy (Quantity): Transition energy between low- and high-energy hadronic models. If omitted, use the CORSIKA build default.
nsb_energy_range (str): NSB gamma energy range (default: “20 MeV 25 MeV”).
proton_energy_range (str): Proton energy range (default: “2 GeV 2000 GeV”).
nsb_scaling_factor (float): NSB scaling factor used for both curves (default: 2).
trigger_thresholds (float, int, float, optional): Three values defining the trigger-threshold scan used for both curves: minimum threshold, number of thresholds, and step size. Trigger-dependent defaults are used when omitted.
output_path (Path): Root output directory; nsb/ and proton/ sub-dirs are created inside it (provided by framework, default: ./simtools-output/).

Example

simtools-generate-bias-curve-submissions \
    --site North \
    --model_version 7.0.0 \
    --array_layout_name LSTN-01 \
    --azimuth_angle 0.0 \
    --zenith_angle 20.0 \
    --showers_per_run 10000 \
    --core_scatter "20 1900 m" \
    --view_cone "0 deg 5 deg" \
    --number_of_runs 10 \
    --nsb_energy_range "20 MeV 25 MeV" \
    --proton_energy_range "2 GeV 2000 GeV" \
    --nsb_scaling_factor 2 \
    --trigger_thresholds 220 3 10 \
    --output_path ./bias_curves

Submit files can be generated explicitly for a chosen backend, for example:

simtools-simulate-prod-htcondor-generator \
    --job_grid_file ./bias_curves/nsb/scan_grid.ecsv \
    --output_path ./bias_curves/nsb/htcondor_submit \
    --apptainer_image /path/to/image.sif \
    --label nsb

Command line arguments#

options#

–help

show this help message and exit

–nsb_energy_range

Energy range for the NSB gamma curve.

Default: (<Quantity 20. MeV>, <Quantity 25. MeV>).

–proton_energy_range

Energy range for the proton curve.

Default: (<Quantity 2. GeV>, <Quantity 2000. GeV>).

–nsb_scaling_factor

NSB scaling factor used for both curves.

Default: 2.0.

–trigger_thresholds

Define evenly spaced trigger thresholds for both curves as MIN_THRESHOLD NUMBER_OF_THRESHOLDS STEP_SIZE.

simulation model#

–site

Observatory site (e.g., North, South). Use –show_options site.

Required.

–model_version

Simulation production model version(s). Use –show_options model_version.

Required.

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

Required.

simulation software#

–simulation_software

Simulation software workflow.

Default: corsika_sim_telarray. Choices: corsika, sim_telarray, corsika_sim_telarray.

simulation configuration#

–azimuth_angle

Telescope pointing direction in azimuth. It can be in degrees between 0 and 360 or one of north, south, east or west. North is 0 degrees and the azimuth grows clockwise (East is 90 degrees).

Required.

–zenith_angle

Zenith angle in degrees (between 0 and 180).

Required.

–showers_per_run

Baseline number of CORSIKA showers per run.

Required.

–number_of_runs

Number of runs.

Required.

shower parameters#

–core_scatter

Core positions per shower and maximum scatter radius, e.g. ‘10 500 m’.

Required.

–view_cone

Minimum and maximum view-cone radius, e.g. ‘0 deg 10 deg’.

Required.

corsika configuration#

–corsika_le_interaction

Low-energy interaction model for CORSIKA (default fallback: urqmd). Use –show_options corsika_le_interaction.

Default: urqmd.

–corsika_he_interaction

High-energy interaction model for CORSIKA (default fallback: epos). Use –show_options corsika_he_interaction.

Default: epos.

–corsika_hadronic_transition_energy

Transition energy between the low- and high-energy CORSIKA hadronic interaction models. Unitless values are interpreted as GeV. If omitted, the CORSIKA build default is used.

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.

Example#

Generate LST bias-curve simulation grids#

Create NSB and proton submission grids that scan trigger thresholds for a North-site LST bias curve.

Application: simtools-generate-bias-curve-submissions

Integration test: generate_bias_curve_submissions_lstn-01.yml

Command

simtools-generate-bias-curve-submissions --config tests/integration_tests/config/generate_bias_curve_submissions_lstn-01.yml

Configuration

site: North
model_version: 7.0.0
array_layout_name: LSTN-01
azimuth_angle: 0.0
zenith_angle: 20.0
showers_per_run: 5
core_scatter: 20 1900 m
view_cone: 0 deg 5 deg
number_of_runs: 1
trigger_thresholds:
- 220
- 1
- 10
output_path: simtools-output