naluacq 0.4.5

Library for opening Nalu Scientific data files

NaluACQ

naluacq is a Rust crate for I/O with Nalu Scientific acquisitions in the GbE-compatible format.

The crate encompasses the following:

• Reading acquisitions
• Writing acquisitions (mainly used by naludaq_rs)
• Parsing events from acquisitions
• Calibration of events
• Exporting acquisitions to other formats

Some of these features are made available in the Python (PyO3) bindings for this crate.

Structure of Acquisitions

An acquisition in the new format is a directory containing multiple files describing various aspects of the acquisition.

• {n}.bin - binary event data file "n" (up to 500 MB) containing raw events back-to-back
• {n}.idx - index file containing the offset and length of each event in the corresponding .bin file
• metadata.yml - user-defined string metadata. NaluDAQ uses this to store board parameters and registers.
• readout_metadata - more user-defined binary metadata. NaluDAQ uses this for extra information about the readout.
• [pedestals_calibration] - optional binary file containing pedestal calibration data
• [timing_calibration] - optional binary file containing timing calibration data
• [adc2mv_calibration] - optional binary file containing ADC to mV calibration data

Event Storage

Events are stored in groups of 500 MB maximum known as "chunks." Each chunk is represented using two files: a .bin file which contains the raw event data and an .idx file which points to each event in the .bin file.

Bin File

Events are stored back-to-back in the .bin files as unparsed binary data. A maximum of 500 MB (at the time of writing) is allowed to be stored in a single .bin file. The rough structure is as follows:

1. Metadata Sector
   • 8-byte header indicating file version type and sector length
   • user-defined metadata stored as raw bytes
2. Data Sector
   • Event 1 (raw bytes)
   • Event 2 (raw bytes)
   • ...

Idx File

Because searching through the entire file for a specific event would be painfully slow, an index file is used to store the offset and length of each event in the corresponding .bin file. The index file is comprised of several 8-byte entries, each indicating the offset and length of a single event in the .bin file. A specific event can be found by reading the entry at 8 * index bytes and then reading length bytes from the .bin file starting at offset bytes.

Examples

Reading an Acquisition

use naluacq::Acquisition;

let acq = Acquisition::open("path/to/acquisition.acq").unwrap();

let idx = 0;
let raw_event = acq.get(idx).unwrap()

Parsing an Acquisitions

use naluacq::{Acquisition, Aardvarcv3Event, ParseInto};

let acq = Acquisition::open("path/to/acquisition.acq").unwrap();

let idx = 0;
let raw_event = acq.get(idx).unwrap()

let parsed_event: Aardvarcv3Event = raw_event.parse_into().unwrap();

Building the Documentation

cargo doc --open