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 |
|
2 |
Wavelength from 1/lambda² for rows without one |
G |
|
3 |
Extinction p_atm (plane-parallel airmass by default, zem = emission altitude; curved slant depth with |
G |
|
4 |
Efficiency bound E = product of the |
G |
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 |
|
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 oftelescope_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 corsikaorspherical(corsika-curvedorspherical, and the radius [m]); absent in modenone(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_indexcounts 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
telescopeandtelescope_endrecords beforeevent_end.telescope_end:photonsis 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: theirtelescopeandtelescope_endrecords, 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 table, extinction-table format (required, except with |
|
geometry only, see below |
|
observation level [m a.s.l.] (required) |
|
atmospheric profile (atmprof format): air delay and refraction |
|
efficiency bound of a later factor, two-column text (nm, value); repeatable |
|
wavelengths from 1/lambda² [nm]; default: run keys |
|
Philox seed (required) |
|
output mode (default thinned) |
|
keep column p |
|
single scattering with this scattering table (off by default) |
|
scattering points per photon, 1 to 1024 (default 8; needs |
|
Earth curvature of the atmosphere (default none), see Earth curvature |
|
Earth radius for the curved modes [m] (default 6371315, the CORSIKA CURVED radius) |
|
path inside each telescope [m], finite and ≥ 0 (default 0) |
|
path inside telescope ID (1-based) [m]; overrides |
|
threads for the rows of each chunk, 1 to 256 (default 1); the output does not depend on N |
|
keep only these telescopes (1-based ids); other telescope blocks are dropped and not decoded; not with |
|
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.stateaspending(no source, nopathlen_m), so a later stage applies it.wavelengthisapplied.No transmission table and no
zemare needed.Rejected:
--transmission,--envelope,--mode thinned,--scattering,--scattering-points,--store-p,--pathlen,--telescope-pathlen.--mode weightedis 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 sphericalthe airmass, bending and air delay are spherical (Earth curvature); withcorsikaCORSIKA has applied them.Scattering is plane-parallel and needs sky-frame input and
telescope_r_min 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).