NEREIDS

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 -- resolved Breit-Wigner (single- and multi-level, LRF=1/2), Reich-Moore (LRF=3), and R-Matrix Limited (LRF=7) in its Reich-Moore form (KRM=3), with Coulomb penetrabilities for charged-particle channels and without fission channels; unresolved (LRU=2) ranges are parsed-and-skipped, not evaluated
• Doppler broadening -- Free Gas Model (crystal-lattice model planned, not yet implemented)
• Resolution broadening -- Gaussian (channel width + flight path) and tabulated instrument functions
• ENDF nuclear data -- automatic retrieval and caching (ENDF/B-VIII.0 and VIII.1 from NNDC with IAEA fallback; JEFF-3.3, JENDL-5, TENDL-2023, and CENDL-3.2 from IAEA)
• Counts fitting -- Poisson/KL divergence on raw open-beam and sample counts on time-of-flight bin edges, with analytical Jacobians
• Counts mapping -- parallel fitting of pixel patches as one counts fit
• Python bindings -- full API via PyO3, pip-installable
• Desktop GUI -- egui application with Guided and Studio modes

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

MCP server for AI agents

NEREIDS can run as a local Model Context Protocol server so AI agents can inspect neutron-resonance data, fit spectra, and run spatial density-map workflows through the Python bindings.

pip install "nereids[mcp]"
nereids-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "nereids": {
      "command": "nereids-mcp"
    }
  }
}

The server exposes low-level physics tools (load_endf, compute_cross_sections, compute_transmission, detect_isotopes) and workflow tools for agent-driven processing:

• extract_resonance_manifest(dataset_path) reads an sMCP-style manifest.
• validate_resonance_dataset(dataset_path) checks data, isotope, and resolution configuration.
• process_resonance_dataset(dataset_path) runs a single_spectrum or density_map workflow and writes compact .npz result artifacts.

Datasets can include manifest_intermediate.md, smcp_manifest.md, nereids_manifest.md, nereids_mcp.json, or analysis.json. Markdown manifests use frontmatter between --- delimiters; JSON frontmatter is supported without extra YAML dependencies.

See the MCP server guide for supported data kinds, manifest fields, NeXus histogram handling, and output artifacts.

Minimal spectrum manifest:

---
{
  "name": "venus-hf-spectrum",
  "tool": "nereids",
  "physics": "neutron-resonance",
  "analysis": {
    "mode": "single_spectrum",
    "data": {
      "kind": "counts_npz",
      "path": "aggregated_hf_120min.npz",
      "pc_ratio": 5.98
    },
    "isotopes": [
      {"isotope": "Hf-177", "endf_file": "Hf-177.endf", "initial_density": 1e-5}
    ],
    "fit": {"solver": "kl", "fit_domain": "counts", "max_iter": 100},
    "resolution": {"kind": "none"},
    "output": {"directory": "output"}
  }
}
---

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)

The fit takes raw open-beam and sample counts on shared time-bin edges and a pulse calibration:

import numpy as np
import nereids

u238 = nereids.load_endf(92, 238)

region = nereids.Region(
    open_counts=open_beam_counts,
    sample_counts=sample_counts,
    pixels=1.0,
    background=[nereids.Value.known(0.0)] * 3,
    gamma_transmission=nereids.Value.known(1.0),
    material=nereids.Material(
        isotopes=[(u238, nereids.Value.fitted(1e-5))],
        temperature_k=nereids.Value.known(300.0),
    ),
)
measurement = nereids.Measurement(
    time_edges_us=edges,
    charge_ratio=sample_charge / open_beam_charge,
    normalization=nereids.Value.fitted(1.0),
    regions=[region],
)
calibration = nereids.Calibration(
    t0_us=nereids.Value.known(3.0),
    flight_path_m=nereids.Value.known(25.0),
    pulse=nereids.Pulse(
        alpha0=nereids.Value.known(0.35),
        alpha1=nereids.Value.known(0.05),
        beta0=nereids.Value.known(0.25),
        beta1=nereids.Value.known(0.0),
        r=nereids.Value.known(0.15),
        fwhm_squared_us2=nereids.Value.known(0.0),
        energy_span_ev=(1.0, 200.0),
    ),
)
fit = nereids.fit_counts(measurement, calibration)
print(fit.regions[0].densities, fit.deviance, fit.converged)

nereids.fit_map fits patches of a counts cube in one fit. Every fitted quantity is a Value (known, fitted, within bounds, or measured). See the Python quickstart and the examples/notebooks/ directory.

Architecture

NEREIDS is organized as a Rust workspace with layered crates:

endf-mat              ENDF MAT lookup tables (no deps of its own; used by core + endf)

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       Poisson/KL counts optimizer
    |
nereids-io            TIFF/NeXus I/O, TOF conversion, rebinning
    |
nereids-pipeline      Counts-domain fitting: one region or a map of patches
    |
    +-- nereids-python    PyO3 Python bindings (bindings/python)
    +-- nereids-gui       egui desktop application (apps/gui)

Crate	Description
endf-mat	ENDF MAT number lookup, element symbols, natural isotopic abundances
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, pixel masks
nereids-fitting	Poisson/KL counts optimizer
nereids-pipeline	Counts-domain fitting and pixel-patch 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 -- 18 tutorials organized by complexity

Troubleshooting

Log files

The NEREIDS desktop GUI (nereids-gui) writes daily-rotated log files to a platform-specific data directory, retaining the last 7 days. Each day's file is named nereids-gui.YYYY-MM-DD.log (UTC date):

Platform	Log directory
macOS	~/Library/Application Support/NEREIDS/logs/
Linux	~/.local/share/NEREIDS/logs/ (honours $XDG_DATA_HOME)
Windows	%APPDATA%\NEREIDS\logs\

From the running app, use Help → Open log folder (reveals today's log file in your platform's file manager) or Help → Copy log path to copy the full path to the clipboard.

The default log level is info. Override with the NEREIDS_LOG environment variable (or the standard RUST_LOG), e.g.:

NEREIDS_LOG=debug nereids-gui
NEREIDS_LOG="nereids_pipeline=trace,info" nereids-gui

NEREIDS_LOG takes precedence over RUST_LOG. Panics are captured to the log file with a backtrace before the process exits — please attach the relevant log file when reporting bugs.

Citation

If you use NEREIDS in your research, please cite:

@software{nereids2026,
  author    = {Zhang, Chen and Bilheux, Jean-Christophe and Tang, Shiming and Bilheux, Hassina},
  title     = {{NEREIDS}: Neutron Resonance Resolved Imaging Data Analysis System},
  year      = {2026},
  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

MIT. See LICENSE for details.

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