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

cat

concatenate streams into one, or print a summary

tee

copy a stream to standard output and to files

from-corsika

convert CORSIKA IACT EventIO output to a stream

to-simtel

convert a stream to sim_telarray input

to-grisu

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
  • cat writes one stream with a single stream_end record. --summary prints the records per type and the photons and weight per telescope instead.

  • tee writes the same records to standard output and to each file.

  • obdeect stream --version prints 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.