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 |
|---|---|---|
|
input length units |
Position on the input plane |
|
1 |
Direction cosines; photons move towards -z, |
|
ns |
Time of the bunch at the input plane |
|
input length units |
Emission height (used by the acceptance table only) |
|
photons |
|
|
nm |
Wavelength; 0 draws it from a density or a law |
|
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 > 0keeps that wavelength.A bunch with
wavelength_nm = 0draws one per photon from either:wavelength_density: a piecewise-linear density over nm, by inverse transform; orwavelength_law = (lo_nm, hi_nm): density proportional to 1/lambda^2, sampled exactly aslambda = 1 / (1/lo - u (1/lo - 1/hi)), then truncated tofloor(lambda)as sim_telarray does. Values lie in[floor(lo), hi); the law needs1 <= 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)
fractionis 1, orsize - floor(size)for the last sub-photon of a fractional bunch.acceptanceis an optional table over (wavelength [nm], emission height [m]), bilinear, values in [0, 1]. Without a table it is 1.boundis 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 by1 + 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 weightmin(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.