Conventions#
Units and frames#
User-facing units are in sources. 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
zemisobservation_level_m + z.Angular profiles use
u = 1 - cos(theta), sodOmega = 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
Random numbers. 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 ( |
target |
2 |
point on the target disc ( |
wavelength |
3 |
wavelength |
pulse |
4 |
emission time |
count |
5 |
photon count, photon index 0 only, |
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) andsource_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; resultz ^ (z >> 31).point-source, beam-scan, laser-beam use
seed + i(mod 2^64); night-sky usesseed.
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.