Command line#
All commands are subcommands of obdeect stream. They read photon streams from files or
standard input (-) and write to standard output, so they combine with pipes.
Command |
Purpose |
|---|---|
|
concatenate streams into one, or print a summary |
|
copy a stream to standard output and to files |
|
convert CORSIKA IACT EventIO output to a stream |
|
convert a stream to sim_telarray input |
|
convert a stream to GrOptics photon text (GrOptics and GrISU) |
$ obdeect stream cat run1.pst run2.pst > all.pst
$ obdeect stream cat --summary all.pst
$ obdeect stream cat run.pst | obdeect stream tee copy.pst > out.pst
$ obdeect stream from-corsika run.iact > run.pst
$ obdeect stream to-simtel --camera-map cam.txt run.pst > sim.simtel
$ obdeect stream from-corsika < run.iact | obdeect stream to-simtel > sim.simtel
catwrites one stream with a singlestream_endrecord.--summaryprints the records per type and the photons and weight per telescope instead.teewrites the same records to standard output and to each file.obdeect stream --versionprints the package version and the photon-stream format version.
Every command accepts --help. For complete pipelines see Pipelines.
Camera map and telescope frames#
The camera map lists the camera-frame telescopes, one per line:
# telescope_id mirror_class(1 single | 2 dual) camera_rotation_deg
2 1 0.0
Telescopes not listed are ground-frame (sim_telarray Bypass_Optics=0). Listed telescopes with
camera-frame photons are converted to the bypass convention and need Bypass_Optics=1 (class 1)
or 2 (class 2). obdeect stream to-simtel prints the value for each telescope.
ATMPROF and synthesised headers#
--atmprof FILE reads a CORSIKA/sim_telarray atmospheric table (altitude [km], density, thickness,
n-1 per line, # comments). It is written as ATMPROF (1216) before the first event, with the
profile number that EVTH names (99 for synthesised headers). A stream with its own ATMPROF block
rejects the option.
A stream without CORSIKA blocks gets synthesised headers. The run end (RUNE) carries the number of
events written, so sim_telarray reports the run as complete. The input block (INPUTCFG, one line
NSHOW 0) is written at the start of the run, when the event count is not yet known:
Run(s) completed as expected after 3 events (3 showers).
Telescope-frame photons (dual-mirror telescopes)#
A telescope listed with mirror_class 2 may carry telescope-frame (T) photons instead of
camera-frame photons, for example four flashers at the camera firing onto the secondary mirror.
The T frame has its origin at the secondary centre and z along the optical axis towards the sky.
Each photon is an emission point (x, y, z) with direction (cx, cy, cz) and emission
time t. obdeect stream to-simtel writes one bunch per photon at the plane z = 0 of that frame,
and sim_telarray needs Bypass_Optics=1:
photon: x, y, z = 0.1, 0.2, 0.5 m c = (0.6, 0, -0.8) t = 3 ns observation level 2200 m
bunch: x, y = 47.5, 20.0 cm cx, cy = 0.6, 0 time = 5.085 ns zem = 220050 cm
The bunch position is where the photon’s line crosses z = 0 (path 0.625 m here, also for a photon
moving away from the plane). The time is t plus that path over the speed of light; zem is the
observation level plus z. Without a cz column the photon moves towards the plane. The camera
rotation is not used, and TELPOS z is set to 0 as for camera-frame telescopes.
$ cat cam.txt
1 2 0.0
$ obdeect sources flasher --type secondary --photons 1e6 | obdeect stream to-simtel --camera-map cam.txt | sim_telarray -c <config> -C Bypass_Optics=1 -
obdeect stream to-simtel: telescope 1: telescope frame, mirror class 2, Bypass_Optics=1
Errors: T photons for a telescope without map entry or with mirror_class 1; a photon with
cz = 0; camera-frame and T photons for the same telescope in one run. The efficiency status of
such a telescope is checked as for camera frame.
Efficiency checks#
obdeect stream to-simtel refuses a stream whose efficiency status says
that a factor is still to be applied when sim_telarray does not apply it in that frame. The
error names the factor and exits with status 1:
obdeect stream to-simtel: efficiency status of telescope 2 (camera frame): factor
'telescope_transmission_constant' is pending, but sim_telarray does not apply it in this frame;
apply it upstream (state applied); pass --allow-pending telescope_transmission_constant to accept it as it is
Camera- and telescope-frame photons need the atmosphere applied upstream, for example by
obdeect propagation run. A stream whose status lacks atmosphere is refused:
obdeect stream to-simtel: efficiency status of telescope 1 (camera frame): factor 'atmosphere' is
missing, but sim_telarray does not apply it in this frame; apply it upstream (state applied), or
pass --allow-pending-atmosphere if sim_telarray is meant to apply it
Use --allow-pending-atmosphere only when sim_telarray is meant to apply the atmosphere in that
frame; it accepts an atmosphere that is missing or pending. Use --allow-pending FACTOR (repeatable)
only when the factor is applied elsewhere in the chain,
for example by the camera module. If the QE envelope was applied upstream (state envelope) and
the sim_telarray QE table is divided by that envelope, declare it with --scaled-factor:
$ obdeect stream to-simtel --camera-map cam.txt --allow-pending telescope_transmission_constant run.pst > sim.simtel
$ obdeect stream to-simtel --camera-map cam.txt --allow-pending-atmosphere run.pst > sim.simtel
$ obdeect stream to-simtel --camera-map cam.txt --scaled-factor qe run.pst > sim.simtel
In Python: allow_pending=[...], allow_pending_atmosphere=True and scaled_factors=[...] of
obdeect.stream.stream_to_simtel.
The factors that sim_telarray applies in each frame are listed in Efficiency status.