# Conventions ## Units and frames User-facing units are in [sources](../sources.md#frames-and-units). Here: - Stream frame codes: sky 0, ground 1, telescope (T) 2, camera (C) 3. Sources emit in sky, T or C only. - Sky frame: origin at the observation level above the telescope, z up. Sky z values are heights above the observation level; the column `zem` is `observation_level_m + z`. - Angular profiles use `u = 1 - cos(theta)`, so `dOmega = 2 pi du`, `u in [0, 2]`. - Internally angles are rad; `c = 0.299792458 m/ns`. FWHM to sigma: `sigma = FWHM / 2.35482004503095`. ## Random numbers (contract) The generator, the key fields and the stage ids are described in [](../../stream/random-numbers.md). All draws are `obdeect::stream::uniform4(DrawKey{seed, stage, event, telescope, photon, stream})`, returning four doubles in (0, 1) (Philox-4x32-10). Stage `0x444C0001` (obdeect stream `stage_sources`) for every photon, count and track draw; stage `0x444C0002` (`stage_programs`) for program-level choices. Streams of one photon (each one `uniform4` call, never shared): | Stream | Id | Used for | | --- | --- | --- | | direction | 1 | emission angle (`u[0]`) and azimuth (`u[1]`) of emitters without target; track azimuth; background direction | | target | 2 | point on the target disc (`u[0]` radius, `u[1]` azimuth) or star entrance disc; track position along the segment; background emission point | | wavelength | 3 | wavelength | | pulse | 4 | emission time | | count | 5 | photon count, photon index 0 only, `u[0]` | Photon results depend only on the key, never on chunking, order or threads. Counts, bunch numbers, weights, record order and event numbering are exact; positions and times agree statistically only if the samplers differ, but the key-to-stream assignment above is the contract (counts use `uniform4` exactly as specified so that they are reproduced bit for bit). Seeds: each emission of a tool gets its own seed so emissions never share draws. Two rules exist and are part of the contract: - `derive_seed(base, i)` (flasher, led) and `source_seed(base, i)` (muon-track) are the same function (splitmix64): `z = base + 0x9E3779B97F4A7C15 * (i + 1)` (mod 2^64); `z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9`; `z = (z ^ (z >> 27)) * 0x94D049BB133111EB`; result `z ^ (z >> 31)`. - point-source, beam-scan, laser-beam use `seed + i` (mod 2^64); night-sky uses `seed`. Program-level uniform: `program_uniform(seed, event, draw) = uniform4({seed, 0x444C0002, event, 0, draw, 1})[0]`. ## Rounding to counts A mean `m >= 0` becomes `floor(m) + (u < m - floor(m) ? 1 : 0)` with `u = uniform4({seed, 0x444C0001, event, telescope, 0, 5})[0]`. Not a Poisson draw. ## float32 rule Photon columns x y z cx cy cz t w wavelength (and zem) are float32. All computation is in double; each value is rounded to float32 once when written. Any later arithmetic on a written column (bunch weight, time offset, camera-plane projection, `zem`) is on the float32 values as stated on the pages below. ## Rejecting input Invalid input raises `std::invalid_argument` (C++) or `ValueError` (Python); fields are never silently clamped, dropped or ignored, except where a page says "used as 1" (bunch sizes below 1). ## Magnitude limits `max_magnitude = 1e30`, `max_photon_count = 2^53`. A length, time or wavelength is "within limits" if it is finite and `|x| <= 1e30`; a "positive-within-limits" value additionally is `>= 1e-30`.