Air-shower photons#

trace_bunches traces photon bunches from an air shower from the input plane to the camera entrance, with the model’s responses. It does not apply the atmosphere or the quantum efficiency; the caller applies them (see Transmission convention). Arguments and example: Batch tracing.

Inputs#

Each bunch is size photons (fractional sizes allowed) sharing one position, direction, time, emission height and wavelength.

Column

Unit

Meaning

x, y

input length units

Position on the input plane

cx, cy

1

Direction cosines; photons move towards -z, cz = -sqrt(1 - cx^2 - cy^2)

time_ns

ns

Time of the bunch at the input plane

zem

input length units

Emission height (used by the acceptance table only)

size

photons

ceil(size) sub-photons; the last one has fraction size - floor(size)

wavelength_nm

nm

Wavelength; 0 draws it from a density or a law

bunch_id

uint64

Unique per bunch for one seed

The frame maps input to telescope coordinates: p = R (u x, u y, u plane_z) + offset and d = R (cx, cy, cz), with u metres per input length unit and R orthonormal.

Wavelength#

  • A bunch with wavelength_nm > 0 keeps that wavelength.

  • A bunch with wavelength_nm = 0 draws one per photon from either:

    • wavelength_density: a piecewise-linear density over nm, by inverse transform; or

    • wavelength_law = (lo_nm, hi_nm): density proportional to 1/lambda^2, sampled exactly as lambda = 1 / (1/lo - u (1/lo - 1/hi)), then truncated to floor(lambda) as sim_telarray does. Values lie in [floor(lo), hi); the law needs 1 <= lo < hi, so no value is 0 nm.

Giving both raises ValueError.

Thinning#

For each sub-photon the keep probability is

p_keep = fraction x acceptance(lambda, zem) x bound(lambda)

  • fraction is 1, or size - floor(size) for the last sub-photon of a fractional bunch.

  • acceptance is an optional table over (wavelength [nm], emission height [m]), bilinear, values in [0, 1]. Without a table it is 1.

  • bound is an upper bound of the responses at that wavelength: the maximum reflectivity over incidence angle (primary and secondary), the maximum degradation factor, and the on-axis telescope transmission. It is multiplied by 1 + 1e-12.

A sub-photon is kept if draw < p_keep, where draw is the first number of the Philox stream of (seed, bunch_id, sub_photon). Survivors are recorded before tracing.

Roulette#

Each survivor is traced with the responses. A detected photon of weight w is kept with probability min(1, (w / norm) / bound), using the second number of the same draw.

  • roulette=True (default): kept photons have weight 1.

  • roulette=False: all detected survivors stay, with weight min(1, w / norm / bound).

norm is 1, or the on-axis transmission t0 with normalise_transmission=True. That setting divides the bound and the roulette weight by t0, so output weights are relative to t0; the caller then applies t0. If the model has no transmission, or t0 is not positive, the divisor is 1. The expected weight of a bunch equals the sum of weights of a full trace.

Transmission convention#

The telescope transmission is a response of the model. With the default normalise_transmission=False, the output weights carry it in absolute terms. The simtools shower route uses this setting. Under Bypass_Optics, sim_telarray takes the airmass from the camera-frame direction of each bunch, not from the sky direction. So the route multiplies each weight by the ratio of the native transmission to the transmission sim_telarray applies, computed with sim_telarray’s formula at the ground airmass and the bypass airmass. sim_telarray then applies the rest (bypass transmission and quantum efficiency). The total equals the native chain. See Validation.

Input plane#

The input plane must lie above every incoming obscurer, such as the camera housing. Photons starting below an obscurer never meet it. The plane is n . p = value with normal n = R e_z. Before tracing, trace_bunches compares it with each incoming obscurer’s highest point along n. If the plane passes below that point, it raises ValueError naming the obscurer and the height along the telescope axis, value / n_z. Raise plane_z to fix it.

frame_offset_m is the input origin in the telescope frame. For a model with an axes offset (see Optical models), the native tracer subtracts that offset. A ground-frame point P is then traced at R P + frame_offset_m - O, which is R (P - O_ground) for the ground-frame offset O_ground of the sim_telarray axes_offsets record. This assumes frame_rotation is the ground-to-telescope rotation at the compiled zenith angle.

Time reference#

Output time_ns is the input time_ns plus the path from the input plane through the optics, times the model’s propagation_group_index, divided by the speed of light. No delay is added for telescope height or airmass.

Determinism#

The random numbers of a sub-photon depend only on (seed, bunch_id, sub_photon). The output does not depend on threads, chunking or bunch order. Bunch ids must be unique per seed. The recommended id is (event_number << 32) | bunch_index_in_event, with a seed per telescope derived from the run seed and the telescope number.

Not modelled#

  • Atmosphere (absorption, airmass) and quantum efficiency. Applying them inside obdeect ray tracing is later work.

  • Cherenkov emission, shower development and the CORSIKA input format (in simtools).

  • Electronics, pixel readout, triggers and event output.

  • Scattering or absorption that the model does not describe as a response.