Python API Reference

The nereids Python package is a PyO3 layer over the Rust pipeline. This page is a curated narrative reference covering the typed APIs Python users reach for most often, with argument tables, array-shape contracts, and dispatch rules.

For the exhaustive auto-generated reference (every function, class, and attribute exported by the package), see the generated Python API reference built by pdoc from the installed wheel and the shipped nereids/__init__.pyi type stubs.

Install the base package with:

pip install nereids

Optional extras are:

pip install "nereids[mcp]"  # MCP server console script
pip install "nereids[gui]"  # GUI wheel dependency, when available for your platform

Data Objects

ResonanceData

Returned by load_endf(...), load_endf_file(...), and create_resonance_data(...).

Important properties:

FitResult

Returned by fit_spectrum_typed(...) and fit_counts_spectrum_typed(...).

InputData

Opaque typed 3D input for spatial mapping. Create it with:

data = nereids.from_transmission(transmission, uncertainty)
data = nereids.from_counts(sample_counts, open_beam_counts)

The spectral axis is always axis 0, so arrays have shape (n_energy, height, width).

SpatialResult

Returned by spatial_map_typed(...).

NexusData

Returned by load_nexus_histogram(...) and load_nexus_events(...).

ENDF Loading

u238 = nereids.load_endf(92, 238, library="endf8.1")
u238_local = nereids.load_endf_file("examples/data/u238_ex027.endf")

load_endf(...) fetches and caches evaluated nuclear data. Supported library names include endf8.0, endf8.1, jeff3.3, jendl5, tendl2023, and cendl3.2. First use can require network access; cached files are reused afterwards. load_endf_file(...) parses a local ENDF file and does not download data.

Forward Modeling

import numpy as np
import nereids

u238 = nereids.load_endf(92, 238)
energies = np.linspace(1.0, 30.0, 2000)

transmission = nereids.forward_model(
    energies,
    [(u238, 0.001)],
    temperature_k=300.0,
    flight_path_m=25.0,
    delta_t_us=5.0,
    delta_l_m=0.005,
)

forward_model(...) returns a 1D float64 transmission spectrum on the input energy grid. Pass either isotopes=[(ResonanceData, density), ...] or groups=[(IsotopeGroup, density), ...], but not both. Gaussian resolution is enabled by the flight_path_m, delta_t_us, and delta_l_m parameters. Tabulated resolution can be supplied with resolution=load_resolution(...).

Single-Spectrum Fitting

Transmission Data

result = nereids.fit_spectrum_typed(
    transmission,
    uncertainty,
    energies,
    [(u238, 0.0005)],
    temperature_k=300.0,
    solver="lm",
)

Shape contract:

• transmission, uncertainty, and energies are 1D arrays with the same length.
• energies is in eV and should be ascending.
• isotopes supplies (ResonanceData, initial_density) pairs.

Keyword arguments:

Raw Counts

result = nereids.fit_counts_spectrum_typed(
    sample_counts,
    open_beam_counts,
    energies,
    [(u238, 0.0005)],
    solver="auto",
    c=1.0,
)

solver="auto", "kl", "poisson", and "joint_poisson" all route counts data to the counts-KL dispatch. Use c=Q_s / Q_ob when sample and open-beam counts have different proton charge or dwell-time normalization. The primary GOF for this path is FitResult.deviance_per_dof.

Counts fitting accepts the same temperature, background, group, resolution, energy-scale, and fit_energy_range options as transmission fitting. Counts specific options are:

Spatial Mapping

Pre-Normalized Transmission Cubes

data = nereids.from_transmission(transmission_3d, uncertainty_3d)
result = nereids.spatial_map_typed(
    data,
    energies,
    [u238],
    initial_densities=[0.0005],
    solver="auto",
)

For from_transmission(...) inputs the default solver="lm" and solver="auto" both route to LM (this is the dispatcher contract in __init__.pyi: “from_transmission + solver="lm" (default for transmission) → LM”). The explicit solver="kl" opt-in for from_transmission runs the legacy Poisson-NLL-on-transmission path. density_maps[0] is the fitted U-238 map.

Raw Count Cubes

data = nereids.from_counts(sample_counts_3d, open_beam_counts_3d)
result = nereids.spatial_map_typed(
    data,
    energies,
    [u238],
    initial_densities=[0.0005],
    solver="auto",
    c=1.0,
)

solver="auto" uses counts-KL for from_counts(...) data and populates deviance_per_dof_map.

Shape contract:

• sample_counts_3d, open_beam_counts_3d, transmission_3d, and uncertainty_3d use shape (n_energy, height, width).
• energies.shape == (n_energy,).
• dead_pixels, when supplied, uses shape (height, width) with True marking pixels to skip.

Keyword arguments:

TIFF and NeXus I/O

stack = nereids.load_tiff_stack("transmission_stack.tif")
folder_stack = nereids.load_tiff_folder("frames", pattern="frame_*.tif")

sample = nereids.load_nexus_histogram("sample.nxs")
open_beam = nereids.load_nexus_histogram("open_beam.nxs")
energies = nereids.tof_to_energy_centers(
    sample.tof_edges_us,
    sample.flight_path_m or 25.0,
)

See Data I/O and NeXus/TOF for ordering and pairing rules.

Element and Utility APIs

nereids.element_symbol(92)        # "U"
nereids.element_name(92)          # "Uranium"
nereids.parse_isotope_str("U-238") # (92, 238)
nereids.natural_abundance(92, 238)
nereids.natural_isotopes(26)
nereids.tof_to_energy(tof_us, flight_path_m)
nereids.energy_to_tof(energy_ev, flight_path_m)

How This Page Is Generated

The published docs site renders three things side by side:

To rebuild the whole site locally:

pixi run doc-build   # depends on: doc-guide, doc-api, doc-python
pixi run doc         # serves target/book/ at http://localhost:8000

doc-python invokes pdoc -o target/book/python --no-show-source nereids after pixi run build has produced an importable wheel. Whenever bindings/python/python/nereids/__init__.pyi or PyO3 docstrings in bindings/python/src/lib.rs change, both the auto-generated python/ reference and any affected sections of this curated page should be reviewed in the same PR.

This page does not execute notebooks or compile-test Python snippets. The Rust quickstart on this site IS compile-tested by cargo check --workspace --examples (see crates/nereids-fitting/examples/quickstart.rs).