Photon streams#

obdeect ray-tracing trace-stream traces a photon stream through an optical model and writes the camera-frame photons. Frames and records are defined in the photon-stream format.

obdeect ray-tracing trace-stream --model telescope.json --seed 7 -i ground.pst -o camera.pst
obdeect ray-tracing trace-stream --model telescope.json --seed 7 --telescopes 1,2 < in.pst > out.pst

Records pass through; telescopes not listed in --telescopes are dropped. A summary (events, photons in and out) goes to standard error. - (the default) is standard input or output.

Input frames#

Frame

Photons

Requirements

G (1)

Ground plane z = 0 through the telescope sphere centre; array axes (x north, y west, z up)

Pointing: --pointing-zenith-deg and --pointing-azimuth-deg (deg), or the run keys telescope_pointing_zenith_rad and telescope_pointing_azimuth_rad (rad). The azimuth is the telescope azimuth in the array frame (simtools’ phi), not the CORSIKA shower azimuth azimuth_rad, which is not used.

T (2)

Telescope frame of OpticalModel.trace (+z along the optical axis, towards the sky)

Column z

Other frames are rejected. The input columns x y cx cy t w are required. wavelength is used when present, and zem is copied to the output. A wavelength of 0 is drawn from the run keys wavelength_min_nm and wavelength_max_nm, as in CORSIKA. A cz column must agree with cx and cy. Column p (acceptance already applied) is rejected, because the stage does not reweight by it.

Each photon moves along its direction to an input plane above the incoming obscurers, using their directional support for the pointing. Its time advances by the path length over the speed of light. The G rotation is the ground-to-telescope rotation of simtools, so a shower from the optical axis maps to direction (0, 0, -1). For a telescope at zenith 20° and array azimuth 0°:

--pointing-zenith-deg 20 --pointing-azimuth-deg 0

Do not pass the CORSIKA shower azimuth (EVTH PHIP); it is a different quantity.

Output frame (C)#

Column

Unit

Meaning

x, y

m

Position on the focal surface, telescope frame; z = 0 is implicit

cx, cy, cz

1

Direction in the telescope frame; reflected photons have cz > 0 (towards the camera)

t

ns

Arrival time

w

photons

Weight (1 per survivor, or the weight corrected for the efficiency bound)

wavelength

nm

Wavelength

zem

m a.s.l.

Only if the input has it

Axes follow the telescope frame of the optical models. Chunks hold at most 2^16 rows; first_index counts the output rows of each telescope and event. Random numbers: Random numbers.

Efficiency status#

The optical model applies mirror_reflectivity and, when present, telescope_transmission (or structure shadowing). Their states are carried in efficiency_status records. The stage reads each factor’s state from the run level or the telescope level; the telescope level overrides the run level.

State

Action

absent or pending

The factor is applied in full by the trace.

envelope

The stream carries the efficiency bound f_env, so the output weight is multiplied by 1 / f_env(λ). The trace then gives f / f_env. Photons are traced with roulette=False (weights min(1, w / bound) per survivor), so weights stay unbiased; the table is interpolated at each photon’s wavelength.

applied

An error: the trace would apply the factor again.

Other factors (for example qe) pass on unchanged. After the run record, the stage writes a efficiency-status record after the incoming run statuses, marking the factors it applies applied, with source set to obdeect and the model hash. Input records naming these factors are rewritten the same way. For example, a run record with mirror_reflectivity.state = envelope (table over 300 to 600 nm) becomes:

factors = mirror_reflectivity,telescope_transmission
mirror_reflectivity.state = applied
mirror_reflectivity.source = obdeect 0.7.2 model <sha256>
telescope_transmission.state = applied
...

telescope_end records get the sum of the output weights of their telescope.

Telescope transmission#

--telescope-transmission full (default) applies t(θ), including its on-axis value t0. --telescope-transmission angular applies t(θ) / t0 only, for a camera module that applies t0 itself. The weight per photon is unchanged; the expected sum of output weights of an on-axis photon is 1 / t0 times that of full, so the camera multiplies by t0 to recover it. angular needs a model with telescope transmission and a positive on-axis value. Both modes write the same keys, with the choice recorded in telescope_transmission.part. In angular mode the status also lists the remaining factor and its on-axis value:

factors = mirror_reflectivity,telescope_transmission,telescope_transmission_constant
telescope_transmission.state = applied
telescope_transmission.part = angular
telescope_transmission_constant.state = pending
telescope_transmission_constant.value = 0.9

A telescope-level record naming telescope_transmission gets the same entries. A record that already names telescope_transmission_constant is rejected in angular mode.

Not applied here#

Atmosphere, quantum efficiency and camera responses are applied in later stages.