nereids 0.1.8

Neutron Resonance Imaging Data Analysis Library

NEREIDS

Neutron rEsonance REsolved Imaging Data analysis System

NEREIDS is a Rust-based library for neutron resonance imaging at the VENUS beamline, Spallation Neutron Source (SNS), Oak Ridge National Laboratory. It provides end-to-end analysis for time-of-flight neutron transmission imaging: input hyperspectral TOF data, output spatially resolved isotopic composition maps.

Features

• R-matrix cross-sections -- Reich-Moore, SLBW, R-Matrix Limited (LRF=7), Unresolved Resonance Region (URR/Hauser-Feshbach), Coulomb channels
• Doppler broadening -- Free Gas Model (crystal-lattice model planned, not yet implemented)
• Resolution broadening -- Gaussian (channel width + flight path) and tabulated instrument functions
• ENDF/B data -- automatic retrieval and caching from IAEA for all evaluated libraries (ENDF/B-VIII.0, ENDF/B-VIII.1, JEFF-3.3, JENDL-5, TENDL-2023)
• Spectrum fitting -- Levenberg-Marquardt and Poisson/KL divergence optimizers with analytical Jacobians
• Spatial mapping -- parallel per-pixel fitting via rayon for 2D isotopic density maps
• Detectability analysis -- energy-window optimization for trace element sensitivity
• Python bindings -- full API via PyO3, pip-installable
• Desktop GUI -- egui application with guided workflow and studio mode

Installation

Python (recommended)

pip install nereids

Requires Python >= 3.10. Prebuilt wheels are available for Linux (x86_64), macOS (ARM), and Windows (x86_64).

Rust

Add individual crates to your Cargo.toml:

[dependencies]
nereids-core = "0.1"
nereids-endf = "0.1"
nereids-physics = "0.1"

GUI application

macOS (Homebrew):

brew tap ornlneutronimaging/nereids
brew install --cask nereids

macOS/Linux (pip):

pip install nereids-gui
nereids-gui

From source

git clone https://github.com/ornlneutronimaging/NEREIDS.git
cd NEREIDS
cargo build --workspace --release
cargo test --workspace --exclude nereids-python

Python bindings require maturin:

pip install maturin
maturin develop --release -m bindings/python/Cargo.toml

Quick Start (Python)

import numpy as np
import nereids

# Load ENDF resonance data
u238 = nereids.load_endf(92, 238)
fe56 = nereids.load_endf(26, 56)

# Energy grid (1-200 eV covers the strong U-238 resonances)
energies = np.linspace(1.0, 200.0, 5000)

# Forward model: transmission through a mixed sample
transmission = nereids.forward_model(
    energies,
    isotopes=[(u238, 0.005), (fe56, 0.01)],  # (data, areal density in at/barn)
    temperature_k=293.6,
)

# Spatial mapping with typed API
trans_3d = transmission[:, None, None] * np.ones((1, 4, 4))  # (n_e, ny, nx)
sigma_3d = np.full_like(trans_3d, 0.01)
data = nereids.from_transmission(trans_3d, sigma_3d)
result = nereids.spatial_map_typed(data, energies, [u238, fe56])

print(f"Converged: {result.n_converged}/{result.n_total} pixels")

See the examples/notebooks/ directory for 17 tutorial notebooks covering foundations, building blocks, workflows, and applications.

Architecture

NEREIDS is organized as a Rust workspace with layered crates:

nereids-core          Shared types, physical constants, isotope registry
    |
nereids-endf          ENDF file retrieval, parsing, resonance data
    |
nereids-physics       Cross-sections, broadening, transmission model
    |
nereids-fitting       LM and Poisson/KL optimizers
    |
nereids-io            TIFF/NeXus I/O, TOF normalization, rebinning
    |
nereids-pipeline      End-to-end orchestration, spatial mapping (rayon)
    |
    +-- nereids-python    PyO3 Python bindings
    +-- nereids-gui       egui desktop application

Crate	Description
nereids-core	Core types, physical constants, traits
nereids-endf	ENDF file retrieval, caching, resonance parameter parsing
nereids-physics	Cross-section calculation, broadening, transmission model
nereids-io	TIFF/NeXus data I/O, VENUS normalization
nereids-fitting	Optimization engine (LM, Poisson/KL)
nereids-pipeline	End-to-end orchestration and spatial mapping
nereids-python	PyO3 Python bindings for Jupyter
nereids-gui	egui desktop application

Documentation

• User Guide -- Installation, quickstart, architecture
• API Reference -- Rustdoc for all crates
• Jupyter Notebooks -- 17 tutorials organized by complexity

Citation

If you use NEREIDS in your research, please cite:

@software{nereids2025,
  author    = {{ORNL Neutron Imaging Team}},
  title     = {{NEREIDS}: Neutron Resonance Resolved Imaging Data Analysis System},
  year      = {2025},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18973054},
  url       = {https://doi.org/10.5281/zenodo.18973054}
}

Contributing

See CONTRIBUTING.md for development setup, coding standards, and the PR process.

License

BSD-3-Clause. See LICENSE for details.

Copyright (c) 2025, UT-Battelle, LLC, Oak Ridge National Laboratory.