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: |
T (2) |
Telescope frame of |
Column |
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 |
|---|---|---|
|
m |
Position on the focal surface, telescope frame; z = 0 is implicit |
|
1 |
Direction in the telescope frame; reflected photons have cz > 0 (towards the camera) |
|
ns |
Arrival time |
|
photons |
Weight (1 per survivor, or the weight corrected for the efficiency bound) |
|
nm |
Wavelength |
|
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 |
The factor is applied in full by the trace. |
|
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 |
|
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.