Module nexus 

NeXus/HDF5 reading for rustpix-processed neutron imaging data.

Supports two data modalities from rustpix output files:

• Histogram: 4D counts array (rot_angle, y, x, tof). The loader requires the caller to choose how multi-angle files are handled via MultiAngleMode (error, sum, or select-angle) and transposes the chosen 3D slice to NEREIDS convention (tof, y, x).
• Events: per-neutron (event_time_offset, x, y) histogrammed into a (tof, y, x) grid with user-specified binning parameters.

Multi-angle handling (issue #430)

Earlier revisions of this module silently summed multi-angle histograms into a single (tof, y, x) volume at load time — an irreversible data loss in the import path. The default now is to refuse multi-angle files via MultiAngleMode::Error; callers who genuinely want the legacy sum-over-angles behaviour opt in explicitly with MultiAngleMode::Sum, and callers who want to work with a single projection from a multi-angle acquisition choose MultiAngleMode::SelectAngle.

HDF5 Schema (rustpix convention)

/entry/histogram/counts          — u64 4D [rot_angle, y, x, tof]
/entry/histogram/time_of_flight  — f64 1D, TOF axis (see "Units" below)
/entry/neutrons/event_time_offset — u64 1D, TOF per event (see "Units" below)
/entry/neutrons/x                — f64 1D, pixel coordinate
/entry/neutrons/y                — f64 1D, pixel coordinate
/entry/pixel_masks/dead          — u8  2D [y, x]

Metadata attributes on /entry or group level:

• flight_path_m (f64)
• tof_offset_ns (f64)

Units convention

Canonical internal TOF unit: microseconds (µs). Every TOF quantity returned to NEREIDS callers — tof_edges_us, EventBinningParams::tof_min_us/tof_max_us, downstream nereids_io::tof energy conversions — is in µs. All other parts of the pipeline (energy mapping, normalization, fitting) assume µs.

On read, both time_of_flight (histogram path) and event_time_offset (events path) consult the HDF5 units attribute on the dataset (the NeXus/NXtof convention) and rescale to µs accordingly:

units attribute	Rescale to µs
ns, nanoseconds	× 1e-3
us, µs, microseconds	× 1
ms, milliseconds	× 1e3
s, seconds	× 1e6
(missing)	× 1e-3 (assume ns — rustpix legacy default)
anything else	hard error

The “missing → assume ns” fallback preserves backward compatibility with the rustpix producer (scripts/fixtures/extract_venus_hf_nexus.py) which writes nanoseconds without a units attribute. Any file that does set units is parsed strictly: an unrecognised value is rejected rather than silently mis-scaled. This closes a 1000× silent-rescale bug on units = "us" (issue #554).

Structs

EventBinningParams

Parameters for histogramming neutron event data into a 3D grid.

EventRetentionStats

Statistics on how many events were kept vs dropped during histogramming.

Hdf5TreeEntry

An entry in the HDF5 group/dataset tree hierarchy.

NexusHistogramData

Histogram data loaded from a NeXus file, ready for NEREIDS processing.

NexusMetadata

Metadata probed from a NeXus/HDF5 file without loading full data.

Enums

Hdf5EntryKind

Kind of HDF5 tree entry.

MultiAngleMode

Policy for handling multi-angle NeXus histogram files.

Functions

list_hdf5_tree

List the group/dataset tree structure of an HDF5 file.

load_nexus_events

Load neutron event data from a NeXus file and histogram into a 3D grid.

load_nexus_histogram

Load histogram data from a NeXus file, refusing multi-angle inputs.

load_nexus_histogram_with_mode

Load histogram data from a NeXus file with an explicit multi-angle handling policy. See MultiAngleMode for the options.

probe_nexus

Probe a NeXus/HDF5 file for available data modalities and metadata.