Atmosphere stage#

obdeect propagation run (command line) and obdeect.propagation.propagate (Python) apply the atmosphere to a photon stream. They move photons from their emission point to the telescope, then apply the atmospheric effects of each chunk in a fixed order. Each effect is recorded in the output efficiency status.

Use them for photons in the sky frame: air showers read with obdeect stream from-corsika and the sky-frame light sources. The output is in the ground frame (G).

Stages#

Per telescope and event, without scattering:

#

Step

Frame

Reference

1

Straight line from the emission point to the horizontal plane through the telescope sphere centre; bending (refraction) unless the run says it is applied; air delay

sky → G

Refraction and timing

2

Wavelength from 1/lambda² for rows without one

G

Atmospheric extinction

3

Extinction p_atm (plane-parallel airmass by default, zem = emission altitude; curved slant depth with --curvature)

G

Atmospheric extinction, Earth curvature

4

Efficiency bound E = product of the --envelope tables; thinning or weighting

G

Atmospheric extinction

With --scattering, one more step runs per event, before the steps above:

#

Step

Frame

Reference

0

Single scattering of the primary photons (downwards): wavelengths first, then scattered photons towards every telescope sphere, in their telescope’s block

sky

Single scattering

1–4

Primaries: as above (p = p_atm E)

sky → G

1s

Scattered photons: sky → G, same run geometry (refraction, air delay)

sky → G

4s

Scattered photons: p = E exp(-od_focus), thinning or weighting (own random stream, see Random numbers)

G

Scattered photons skip steps 2 and 3. Their transmission from the scattering point to the telescope sphere is already in w (T(P → C) of Single scattering), so the atmosphere is not applied twice. Step 4s adds only the in-telescope part exp(-od_focus(lambda)) of their telescope (the same od_focus as step 4, so the path length applies to them too; with a path of 0 m the factor is 1). The primaries are scattered before their own extinction and are otherwise unchanged.

An event is held until its event_end record, because the scattered photons of a telescope come from the primaries of all telescopes of the event. Memory: one event of the input.

To add an effect, add a step in Propagator::photons (cpp/include/obdeect/propagation/propagator.hpp) and an entry in the list of efficiency factors built there.

Frames and positions#

  • Sky: x (north), y (west), z above the observation level; direction cosines (cx, cy, cz), cz < 0 downwards. An optional cz column decides whether a photon moves upwards.

  • Telescope i (1-based telescope_id) is at the i-th entry of telescope_x_m, telescope_y_m, telescope_z_m (z above the observation level).

  • G: x, y relative to the telescope centre; z and cz are removed.

  • Emission altitude a.s.l. = observation_level_m + z. Telescope altitude a.s.l. = the same plus the telescope z.

A photon in the sky frame reaches the plane if it moves downwards and starts above it. Other photons (upwards, horizontal, emitted below the plane, or not bendable) are dropped and counted. Their rows stay in the chunk with w = 0, so the random draws of the other photons do not change.

Time: without a profile, t + s/c. With a profile and no refraction in the stream, the air delay straight_path_air_delay_ns is added. With refraction (refraction_applied = 0 and a profile), time and direction come from bend at the telescope plane (Refraction and timing). In spherical mode the bending and air delay are the spherical integrals of Earth curvature instead.

Efficiency status#

One efficiency_status record follows each run record (before the first record that is not an efficiency-status record). Example:

factors                 atmosphere,wavelength,scattering,qe
atmosphere.state        applied
atmosphere.source       atm_trans_2000_1_10_0_0_2000.dat
atmosphere.pathlen_m    [28, 0]
wavelength.state        applied
wavelength.range_nm     [250, 700]
scattering.state        applied
scattering.source       scattering_exponential.dat
scattering.points_per_photon 8
qe.state                envelope
qe.source               qe.dat
qe.wavelength_nm        [200, 800]
qe.value                [0.9, 0.5]
  • atmosphere: applied; source = transmission file; pathlen_m = path inside each telescope [m], in telescope_id order (entry 0 is telescope 1).

  • atmosphere.geometry, atmosphere.earth_radius_m: only with --curvature corsika or spherical (corsika-curved or spherical, and the radius [m]); absent in mode none (Earth curvature).

  • wavelength: applied; rows without a wavelength get one from the range.

  • scattering: only with scattering; applied; source = scattering table; points per photon.

  • Each efficiency bound: state envelope (its value is part of the thinning, not applied in full), with its table.

The stage refuses an input stream whose efficiency status shows atmosphere, scattering or an efficiency bound as applied (pending or absent is fine). Input records are passed through before the stage’s own record. Readers merge the efficiency-status records of a stream in order. The record format is described in Efficiency status.

Output#

  • Thinned (default): one row per surviving photon, w = 1 (Atmospheric extinction). first_index counts output rows per telescope and event.

  • Weighted: all rows with w multiplied by p; rows with w = 0 removed.

  • Column p is written only with --store-p (store_p).

  • run: refraction_applied = 1 when a profile is given.

  • telescope: frame set to G.

  • Scattered photons of telescope t are in its block, after the primaries. A telescope with scattered photons but no input block gets its own telescope and telescope_end records before event_end.

  • telescope_end: photons is the sum of w of the output.

  • Other records (event, blob, end records) are passed through. The output stream record comes from the writer; the input one is not copied.

  • With a telescope selection (--telescopes), the blocks of other telescopes are removed: their telescope and telescope_end records, photons and telescope status. The format allows any subset of telescope blocks in an event (telescope photons* telescope_end, repeated). Their photons are not decoded. Run and event records are unchanged.

Command line#

$ obdeect propagation run --transmission atm_trans_2000_1_10_0_0_2000.dat --site-altitude 2000 \
    --profile atmprof.dat --envelope qe=qe.dat --envelope mirror=mirror.dat \
    --wavelength-range 250 700 --seed 1 -i in.pst -o out.pst
obdeect propagation run: photons in <n>, out <m> (weight <w>), dropped <d>

Option

Meaning

--transmission FILE

transmission table, extinction-table format (required, except with --no-extinction)

--no-extinction

geometry only, see below

--site-altitude M

observation level [m a.s.l.] (required)

--profile FILE

atmospheric profile (atmprof format): air delay and refraction

--envelope NAME=FILE

efficiency bound of a later factor, two-column text (nm, value); repeatable

--wavelength-range LO HI

wavelengths from 1/lambda² [nm]; default: run keys

--seed N

Philox seed (required)

--mode thinned|weighted

output mode (default thinned)

--store-p

keep column p

--scattering FILE

single scattering with this scattering table (off by default)

--scattering-points N

scattering points per photon, 1 to 1024 (default 8; needs --scattering)

--curvature none|corsika|spherical

Earth curvature of the atmosphere (default none), see Earth curvature

--earth-radius-m M

Earth radius for the curved modes [m] (default 6371315, the CORSIKA CURVED radius)

--pathlen M

path inside each telescope [m], finite and ≥ 0 (default 0)

--telescope-pathlen ID=M

path inside telescope ID (1-based) [m]; overrides --pathlen; repeatable

--threads N

threads for the rows of each chunk, 1 to 256 (default 1); the output does not depend on N

--telescopes ID[,ID...]

keep only these telescopes (1-based ids); other telescope blocks are dropped and not decoded; not with --scattering (default all)

-i FILE|-, -o FILE|-

input and output stream (default stdin, stdout)

Path 28 m for all telescopes, 0 m for telescope 2:

$ obdeect propagation run ... --pathlen 28 --telescope-pathlen 2=0

Keep telescopes 1 and 3 only. The summary counts their photons:

$ obdeect propagation run ... --telescopes 1,3 -i in.pst -o out.pst

The output for the kept telescopes is the same as the full run with the other blocks removed. The summary goes to stderr.

Python#

import obdeect.propagation

summary = obdeect.propagation.propagate(
    "in.pst", "out.pst",
    transmission="atm_trans_2000_1_10_0_0_2000.dat", site_altitude_m=2000.0,
    seed=1, profile="atmprof.dat",
    envelope={"qe": "qe.dat", "mirror": "mirror.dat"},
    wavelength_range=(250.0, 700.0), mode="thinned",
    scattering="scattering_exponential.dat", scattering_points=8,  # optional
    pathlen_m=28.0, telescope_pathlen_m={2: 0.0},                  # optional
    telescopes=[1, 3],                                             # optional
    curvature="spherical", earth_radius_m=6371315.0,               # optional, see curvature.md
)

summary is a dict with photons_in, photons_out, dropped, weight_out. Files are paths only (no -).

Geometry only#

--no-extinction (Python: extinction=False) moves photons from the sky frame to G and assigns wavelengths, and nothing else: no extinction, envelope or thinning. Use it when a later program applies the transmission itself, for example a light source feeding the camera simulation directly.

$ obdeect propagation run --no-extinction --site-altitude 2000 --profile atmprof.dat --seed 1 \
    -i light.pst -o ground.pst
  • Positions, directions and times are those of the normal run (same refraction and air delay).

  • Photons that reach the telescope plane are kept with their weight w; photons that do not (w = 0) are removed, as in weighted mode. There is no column p.

  • The efficiency status records atmosphere.state as pending (no source, no pathlen_m), so a later stage applies it. wavelength is applied.

  • No transmission table and no zem are needed.

  • Rejected: --transmission, --envelope, --mode thinned, --scattering, --scattering-points, --store-p, --pathlen, --telescope-pathlen. --mode weighted is accepted.

In-telescope path#

The extinction inside the telescope covers the path from the telescope sphere plane to the focus. With path length l (pathlen_m), the optical depth is tau(h_T + l) − tau(h_T), with h_T the telescope altitude. --pathlen sets l for all telescopes; --telescope-pathlen (telescope_pathlen_m, 1-based ids) overrides it for single telescopes. Default 0, so existing runs keep their result. Intended l per telescope: the focal length for single-mirror telescopes, |p0-s0|+|s0-f0| for dual-mirror ones (primary, secondary, focus). An id that the run does not have is an error.

Limits#

  • Plane-parallel airmass, straight-line geometry and refraction by default (mode none). With --curvature spherical the airmass, bending and air delay are spherical (Earth curvature); with corsika CORSIKA has applied them.

  • Scattering is plane-parallel and needs sky-frame input and telescope_r_m in the run keys; not available for photons already in frame G, and rejected with a curved mode.

  • The in-telescope path is not derived from the optics (default 0).

  • Transmission tables hold one row per integer nm; a wavelength uses the row at its integer part.

  • Efficiency-bound tables must cover the wavelength range (rounded outwards).

  • In mode none, photons within about 3 degrees of the horizon are not bent and are dropped (series limit of the ray bending, see Refraction and timing).