# 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](../stream/format.md). ```bash 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°: ```bash --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](optical-models.md#frames-and-units). Chunks hold at most 2^16 rows; `first_index` counts the output rows of each telescope and event. Random numbers: [](../stream/random-numbers.md). ## 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: ```text factors = mirror_reflectivity,telescope_transmission mirror_reflectivity.state = applied mirror_reflectivity.source = obdeect 0.7.2 model 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: ```text 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.