HIPO4 C++ Library¶

High Performance Output (HIPO) is a columnar data format and I/O library designed for storing and analyzing experimental physics data from the CLAS12 detector at Jefferson Lab. Files are self-describing (schemas live in the file header) records are LZ4-compressed, and banks are laid out column-major for cache-friendly analysis.

Start here¶

Quick example¶

#include "reader.h"

int main() {
    hipo::reader reader;
    reader.open("data.hipo");

    hipo::dictionary dict;
    reader.readDictionary(dict);

    hipo::bank particles(dict.getSchema("REC::Particle"));
    hipo::event event;

    while (reader.next()) {
        reader.read(event);
        event.read(particles);
        for (int row = 0; row < particles.getRows(); row++) {
            int   pid = particles.getInt("pid", row);
            float px  = particles.getFloat("px", row);
            float py  = particles.getFloat("py", row);
            float pz  = particles.getFloat("pz", row);
        }
    }
}

See the Quick Start for the banklist shortcut, writing files, and the full type system.

Recipes¶

Practical, copy-paste patterns for the common cases:

• Reading files — basic loop, banklist, hipoeventfile, random access, tag filtering, column-index caching.
• Writing files — multi-bank events, user config, copy/filter, generic bank filling.
• Row filtering — lambda, expression strings, cached Parser, cross-bank row linking.
• Parallel processing — the chain class, record-level parallelism, thread-safe accumulation patterns.
• Integration — ROOT RDataFrame, Python hipopy, Julia, Fortran, CMake / Make via pkg-config.

CLAS12 analysis¶

If you're doing physics on CLAS12 reconstructed data, the CLAS12 section covers the patterns specific to that workflow:

• First analysis — the minimum viable CLAS12 loop: open a file, filter charged tracks, histogram the vertex-z.
• The REC:: bank family — REC::Event, REC::Particle, and the detector-level banks that link to them.
• Cross-bank linking via pindex — join REC::Particle to detector banks to compute per-particle quantities like total calorimeter energy.

Reference¶

• Architecture — layered overview and detailed read/write pipelines.
• Data model — records → events → banks → schemas, columnar layout, buffer reuse.
• File format — byte-level header, record, event, and structure layouts.
• Error handling — exception hierarchy, safe-access patterns, bounds-check caveats.
• Performance — optimization tips, throughput numbers, limitations.
• FAQ & troubleshooting — common gotchas and their answers.
• Glossary — terminology cheat sheet.
• API reference — per-class hand-written pages (reader, writer, bank, event, schema, chain, …).
• Doxygen — auto-generated class-and-member reference (planned).

Library info¶