Efficiency status#
Many effects reduce the number of photons that reach the camera: the atmosphere, mirror reflectivity,
quantum efficiency and others. Each module records which of these factors it has already applied,
so that no factor is applied twice or forgotten. The record is efficiency_status; its metadata are:
factors(string): comma-separated factor names, e.g.atmosphere,qe,mirror_reflectivity,telescope_transmission.per factor
<name>.state(string):applied,envelope(only the envelope f^env was applied), orpending.per factor
<name>.source(string): provenance (file name, model version).per factor with a λ table:
<name>.wavelength_nmand<name>.value(float arrays) of the applied (envelope) values.
An efficiency bound (named envelope in options and states) is an upper bound f_k^env of a factor that a module has used early, to thin photons
before the exact factor is known. A module applying factor k with an envelope in the efficiency
status applies f_k / f_k^env and sets <name>.state to applied. A module never applies a factor whose state is applied.
Run status records (before the first event) apply to all telescopes. A telescope status (after
its telescope record, before its photons) applies to that telescope and overrides the run
status per factor. Within either scope, a factor may only advance pending → envelope →
applied; a repeated or backward state is invalid. Telescope updates are checked separately from
run updates before the telescope status overrides the run status.
obdeect stream to-simtel checks the efficiency status of each telescope against the frame of
its photons. It accepts a factor that is applied upstream unless sim_telarray applies it again
in that frame. It accepts pending only for factors that sim_telarray applies in that frame.
envelope is always an error for those factors: sim_telarray applies the full factor, not f/f_env.
For camera- and telescope-frame photons the atmosphere must be applied: a status without
atmosphere, or with it pending, is an error. A stream without any efficiency status is not
checked.
Factor |
Camera frame (C) |
Ground frame (G) |
|---|---|---|
|
sim_telarray applies: pending ok |
sim_telarray applies: pending ok |
|
not applied by sim_telarray: error |
sim_telarray applies: pending ok |
|
must be applied upstream (absent or pending: error) |
any state; with |
|
must be applied upstream |
must be applied upstream |
|
not applied by sim_telarray: error |
not applied by sim_telarray: error |
any other name |
error |
error |
Any other factor (or unknown name) raises an error that names it, unless it is given to
obdeect stream to-simtel --allow-pending FACTOR or allow_pending= in Python. Where sim_telarray
is meant to apply the atmosphere in the camera or telescope frame, use
obdeect stream to-simtel --allow-pending-atmosphere or allow_pending_atmosphere=True in Python.
envelope for a factor that sim_telarray applies is valid only with
obdeect stream to-simtel --scaled-factor FACTOR (scaled_factors= in Python): the sim_telarray
table of the factor then holds f/f_env, e.g. the QE table divided by the QE envelope applied
upstream. Every --scaled-factor needs a matching efficiency status in state envelope; a
missing status or any other state is an error.
The commands that read and write this record: Efficiency checks, Efficiency status, Efficiency status.