Metadata-Version: 2.4
Name: endf-userpy
Version: 0.1.0a2
Summary: High-level interpretation of ENDF-6 data
Home-page: https://github.com/IAEA-NDS/endf-userpy
Author: Georg Schnabel, Daniel Lopez Aldama
License: MIT
Project-URL: Repository, https://github.com/IAEA-NDS/endf-userpy
Project-URL: Issues, https://github.com/IAEA-NDS/endf-userpy/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Fortran
Classifier: Programming Language :: C
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: scipy
Requires-Dist: endf_parserpy
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# endf-userpy

High-level interpretation of ENDF-6 nuclear data files.

`endf-userpy` is a Python library that answers user-friendly questions
about ENDF-6 nuclear data evaluations: "what is the cross section of
the (n,2n) reaction on Fe-56?", "what is the energy spectrum of
neutrons emitted from U-238 at 14 MeV?", "how much Co-60m is produced
per (n,gamma) reaction on Co-59?".

The library does not parse ENDF-6 itself. It builds on
[endf_parserpy](https://github.com/IAEA-NDS/endf-parserpy), which
turns an ENDF-6 file into a nested Python dict (`endf_dict`).
endf-userpy then walks that dict to reconstruct cross sections,
yields, and differential distributions, hiding which MF section a
piece of data lives in.

> **Status.** This is an early alpha release. The public API is
> stabilising but may still change. See "Known limitations" below.
> Feedback by creating issues is appreciated.

## Installation

```bash
pip install endf-userpy
```

Prebuilt wheels are available for cpython 3.9â€“3.13 on:

- Linux x86_64 (`manylinux_2_28`)
- macOS arm64 (>= 14.0)
- macOS x86_64 (>= 15.0)
- Windows AMD64

Other platforms or Python versions install from the sdist
automatically and need a Fortran compiler (`gfortran`) on `PATH`.

Runtime dependencies (`numpy`, `scipy`, `endf_parserpy`) are pulled
in automatically. Some examples additionally use `matplotlib`.

### From source

```bash
git clone https://github.com/IAEA-NDS/endf-userpy
cd endf-userpy
pip install -e .
```

Requires `gfortran` on `PATH`. Windows users who prefer to build
with the Intel Fortran compiler (`ifx`) can opt in by setting
`ENDF_USERPY_USE_IFX=1` in the environment before `pip install`.

## Quick start

```python
import numpy as np
from endf_parserpy import EndfParserFactory
from endf_userpy.quantities import (
    get_available_reactions,
    get_reaction_xs,
)

parser = EndfParserFactory.create()
endf_dict = parser.parsefile("tests/data/n-004_Be_009.endf")

print(get_available_reactions(endf_dict))
# ['(n,total)', '(n,n_0)', '(n,nonelas)', '(n,2n)', '(n,g)', ...]

eincs = np.array([0.0253, 1e3, 1e6, 1.4e7])  # eV
print(get_reaction_xs(endf_dict, "(n,total)", eincs))
# [6.154 6.144 3.341 1.528]   barn
```

## Public API

All user-facing functions live in `endf_userpy.quantities` and take
an `endf_dict` (already parsed) plus user-friendly string identifiers.

| Function | Returns | What it does |
| --- | --- | --- |
| `get_available_reactions(endf_dict)` | list of reaction strings | introspect a file |
| `get_incident_energies(endf_dict, reaction)` | array | tabulated Einc mesh for a channel |
| `get_emission_energies(endf_dict, reaction, particle)` | array | tabulated Eout mesh |
| `get_reaction_xs(endf_dict, reaction, eincs)` | array | cross section of a named channel |
| `get_residual_production_xs(endf_dict, residual, eincs)` | array | production of a specific residual nucleus, isomer-resolved |
| `get_particle_production_xs(endf_dict, reaction, particle, eincs)` | array | ejectile production cross section |
| `get_particle_production_dxs_dE(endf_dict, reaction, particle, eincs, eouts)` | array | dÏƒ/dE energy spectrum of emitted particle |
| `get_particle_production_dxs_dmu(endf_dict, reaction, particle, eincs, mus)` | array | dÏƒ/dÎ© angular distribution |
| `get_particle_production_ddxs(endf_dict, reaction, particle, eincs, eouts, mus)` | array | dÂ²Ïƒ/dE/dÎ© double-differential |

Reaction strings: `"(n,total)"`, `"(n,n_0)"` (elastic), `"(n,2n)"`,
`"(n,g)"` (capture), `"(n,p)"`, `"(n,a)"`, etc.
Particles: `"n"`, `"p"`, `"d"`, `"t"`, `"h"` (helium-3),
`"a"` (alpha), `"g"` (gamma).
Residual nuclei: `"Z-Sym-A"` (e.g. `"27-Co-60"`) or `"Sym-A"`
(e.g. `"Co-60"`), with optional isomer suffix `g`, `m`, `m1`, `m2`,
... (`"Co-60m"` = first metastable).

## Examples

Seven runnable examples in `examples/`:

| File | What it shows |
| --- | --- |
| `01_inspect_file.py` | discover what is in a file |
| `02_reaction_xs.py` | cross sections of named channels with consistency check |
| `03_particle_production_xs.py` | secondary-particle production from Fe-56 |
| `04_residual_production_isomers.py` | Co-58g/m and Co-60g/m via (n,2n) and (n,gamma) |
| `05_emission_spectra_14mev.py` | classic 14 MeV neutron emission spectrum from U-238 |
| `06_ddx_uranium_14mev.py` | double-differential cross section heatmap |
| `07_photonuclear_residuals.py` | (g,Nn) cascade on Au-197 |

Examples 1-2 use a small file shipped under `tests/data/`. Examples 3-7
each include the `wget` command to fetch the JENDL-5 file they need.

## Known limitations

- **No resonance reconstruction.** MF2 (resolved/unresolved resonance
  parameters) is not reconstructed. For evaluations whose MF3 is empty
  in the resonance region, pre-process the file with
  [NJOY RECONR](https://github.com/njoy/NJOY2016) and pass the PENDF
  file in.
- **DDX drops kinematic-delta channels.** The double-differential API
  silently skips elastic and discrete-level inelastic channels because
  they cannot be represented on a continuous Eout grid. They appear in
  the 1D dÏƒ/dE spectrum as sharp peaks instead.
- **Stubs.** `endf_userpy/discrete_quantities.py` and
  `endf_userpy/translation.py` are work-in-progress sketches; do not
  rely on them.

## Filing issues

[github.com/IAEA-NDS/endf-userpy/issues](https://github.com/IAEA-NDS/endf-userpy/issues)

## License and copyright

`endf-userpy` is distributed under the MIT license,
see the `LICENSE` file for details.

Nothing in this license shall be construed as a waiver, either express or implied,
of any of the privileges and immunities accorded to the IAEA by its Member States.

Copyright (c) 2026 International Atomic Energy Agency
