Photon-stream format#
A photon stream is a sequence of records. Integers and floats are little-endian. Lengths are in metres, times in nanoseconds, wavelengths in nanometres and altitudes in metres above sea level.
Record#
Field |
Type |
Meaning |
|---|---|---|
magic |
u32 |
|
type |
u16 |
record type (table below) |
flags |
u16 |
reserved, 0 |
length |
u64 |
payload length in bytes |
payload |
bytes |
|
Readers skip records of unknown type. A stream starts with one stream record and ends with
stream_end.
Type |
Name |
Payload |
|---|---|---|
1 |
|
metadata: |
2 |
|
metadata (run keys below) |
3 |
|
metadata (event keys below) |
4 |
|
metadata: |
5 |
|
photon chunk (below) |
6 |
|
metadata: |
7 |
|
metadata (optional keys) |
8 |
|
metadata (optional keys) |
9 |
|
u32 |
10 |
|
metadata: efficiency status (below) |
15 |
|
empty |
Nesting: stream (run (efficiency_status* (event (telescope photons*
telescope_end)* event_end)* run_end)*) stream_end. blob records may appear anywhere
between run and run_end. An efficiency_status record after a telescope record applies to
that telescope only.
Blobs keep the input order (CORSIKA: RUNH and TELPOS after run; EVTH and TELOFF before the
telescopes; EVTE after them; RUNE before run_end). Writers of EventIO output emit them in that
order. CORSIKA split-mode markers (1213, 1214) are blobs between the telescopes of an event;
obdeect stream to-simtel does not write them.
The format has a major and a minor version (obdeect stream --version prints them). Readers
reject a stream whose format_major differs from theirs and accept any format_minor.
Metadata#
A metadata payload is a u32 entry count followed by entries:
Field |
Type |
|---|---|
key length |
u16 |
key |
UTF-8 bytes |
value type |
u8: 1 = int (i64), 2 = float (f64), 3 = string, 4 = float array |
value |
i64 / f64 / (u32 length + bytes) / (u32 count + f64 values) |
Keys are unique within one payload. Unknown keys are kept.
Run keys (from CORSIKA RUNH and TELPOS, or from obdeect sources): run_number,
observation_level_m, energy_min_gev, energy_max_gev, spectral_index,
n_telescopes, telescope_x_m, telescope_y_m, telescope_z_m,
telescope_r_m (float arrays), atmosphere_id, wavelength_min_nm,
wavelength_max_nm, refraction_applied (int 0/1), curvature_applied (int 0/1).
curvature_applied is 1 if the producer already applied Earth curvature (CORSIKA CURVED
option, EVTH word 79 = 1 or 2); sources write 0.
Event keys (from CORSIKA EVTH and TELOFF): event_number,
primary_id (CORSIKA particle code), energy_gev, zenith_rad,
azimuth_rad (CORSIKA convention), first_interaction_m, core_x_m,
core_y_m, time_offset_ns (float arrays, one entry per array reuse). One
event record per shower; telescope records carry the array_index.
Photon chunk#
Field |
Type |
Meaning |
|---|---|---|
telescope_id |
u32 |
as in the enclosing |
frame |
u32 |
0 = sky, 1 = ground (G), 2 = telescope (T), 3 = camera (C) |
columns |
u32 |
bit mask of present columns (table below) |
rows |
u32 |
number of photons, at most 2^16 |
first_index |
u64 |
index of the first row among all photons of this telescope and event; continues across array reuses (same |
data |
f32 |
one contiguous column of |
Bit |
Column |
Meaning |
|---|---|---|
0 |
|
position x [m] |
1 |
|
position y [m] |
2 |
|
position z [m] (frame sky and T; in G and C the plane is z = 0) |
3 |
|
direction cosine x |
4 |
|
direction cosine y |
5 |
|
direction cosine z (if absent: cz = −sqrt(1 − cx² − cy²)) |
6 |
|
arrival time [ns] |
7 |
|
emission altitude [m a.s.l.] |
8 |
|
weight (photons in the bunch) |
9 |
|
wavelength [nm]; 0 = not yet assigned |
10 |
|
acceptance probability already applied (for reweighting) |
Columns x y cx cy t w are required; the others are optional. A chunk with 0 rows has column
mask 0.
Frames:
sky: absolute emission position (x north, y west, z up, origin at the array centre on the observation level, as CORSIKA) and direction. z is the Cartesian height above the plane through the origin. With Earth curvature (run key
curvature_applied, Earth curvature) the Earth centre lies on the vertical through the origin at z = −(R + observation level).G: horizontal plane through the telescope sphere centre; x and y relative to the centre, CORSIKA axes.
T: telescope-local 3D frame (z along the optical axis towards the sky).
C: camera-neutral focal-plane frame (x, y on the camera entrance, telescope axes, z = 0). Conversion to sim_telarray conventions happens only in
obdeect stream to-simtel.
The efficiency factors that modules apply are recorded in efficiency_status records: Efficiency status. Random numbers: Random numbers. Reading and writing from code: Programming interfaces.