I3Tray Quick Reference¶

Modules¶

First Module¶

The driving module. No inbox, only an outbox.

Options:

I3Reader
I3InfiniteSource
I3CorsikaReader
(some more obscure things)

Intermediate Modules¶

Regular modules. Has both an inbox and an outbox.

Last Module¶

The trashcan. No outbox, only an inbox.

Outboxes¶

Default is “OutBox”

If you have multiple outboxes, they cannot be recombined and must be written to separate files (with separate trashcans).

The outbox is a queue of frames. The module pushes frames onto this queue, which is consumed by the next module’s inbox.

Process¶

The Process function of a module handles internal things

I3Module.Do -> I3Module.Process -> I3Module.DAQ or I3Module.Physics

RequestSuspension¶

Stop calling Process. Once all queues are cleared, I3Tray.Finish is called.

Packet Modules¶

When you have QPPQPP and want to operate on a single packet of QPP. Or maybe you want to reunify QP frames for icetop-inice coincidence.

The packet module buffers frames until we have an entire packet, then processes it.

FramePacket¶

Function that takes a vector of frames (QPP). Otherwise just like Physics function.

Splitter Module¶

Does the reverse, pushing multiple frames per single input frame.

Pointers¶

Note that if you reuse a pointer between frames in the same packet, the previous frame contents can be overwritten. Please do not reuse pointers between frames!

Source¶

The I3PacketModule definition is here: https://github.com/icecube/icetray/blob/main/icetray/public/icetray/I3PacketModule.h

Frame Mixing¶

I3Frame objects have names, streams, and data (key, metadata, value).

Every time you see a frame name, all values get merged into subsequent frames until you see that frame name again.

Details for advanced frame mixing can be found here.

I3Frame::merge¶

Merge things into the active frame in memory.

I3Frame::purge¶

Purge things from the active frame in memory.

PushFrame¶

Every time this is called, the frame is purged and then merged with a cached copy of previous frames.

Note that mixing breaks if you try to add things to a frame after pushing it. (break means strange behavior in this case)

Exceptions¶

The two exceptions for mixing are TrayInfo or Physics frames. These do not mix into other frames.

Examples¶

I3CorsikaReader:

void I3CORSIKAReader::Process()
{
    // Make a new frame.
    I3FramePtr frame(new I3Frame(I3Frame::DAQ));

    // i3_ifs_ is a frame stream.
    // Write frames from file before starting to write
    // our own frames.
    if (!i3_ifs_.empty()) {
        // Get frame from prefix file
        frame->load(i3_ifs_);
        if (i3_ifs_.peek() == EOF)
            i3_ifs_.reset();
        PushFrame(frame);
        return;
    }

    // Fill the frame with CORSIKA info.
    if (FillFrameFromCORSIKA(frame) != 0)
        return; // skip if no CORSIKA info

    // Push the frame to the outbox.
    PushFrame(frame);
}