endf-userpy 0.1.0a1__tar.gz

endf_userpy-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 International Atomic Energy Agency
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

endf_userpy-0.1.0a1/MANIFEST.in

@@ -0,0 +1,43 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+# Fortran and C sources required to build the extension from sdist.
+include endf_userpy/fortran/endf6.f90
+include endf_userpy/fortran/endf6-f2pywrappers.f
+include endf_userpy/fortran/endf6module.c
+
+# Test data, so the test suite is runnable from a sdist checkout.
+recursive-include tests *.py
+recursive-include tests/data *
+include tests/conftest.py
+
+# Numbered example scripts at the top level of examples/.
+include examples/[0-9][0-9]_*.py
+
+# Sphinx sources (not the rendered build).
+recursive-include docs/source *
+include docs/Makefile docs/make.bat
+
+# Build artifacts and scratch files that must never ship.
+global-exclude *.o
+global-exclude *.so
+global-exclude *.pyd
+global-exclude *.pyf
+global-exclude endf6module_active.c
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store
+prune build
+prune dist
+prune testenv
+prune tests_fortran
+prune docs/build
+prune .pytest_cache
+prune .github
+prune endf_userpy.egg-info
+exclude setup.py.bkup
+exclude endf_userpy/daniel_notes.txt
+exclude tests/tmp.py
+exclude tests/manual_test_*.py
+exclude tests/adhoc_test_*.py

endf_userpy-0.1.0a1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: endf-userpy
+Version: 0.1.0a1
+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
+
+Building requires a Fortran compiler (`gfortran` on Linux/macOS,
+`ifx` on Windows) because part of the numerical work is done by a
+f2py extension.
+
+```bash
+pip install -e .
+```
+
+Runtime dependencies: `numpy`, `scipy`, `endf_parserpy`,
+`matplotlib` (only for the examples).
+
+## 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

endf_userpy-0.1.0a1/README.md

@@ -0,0 +1,125 @@
+# 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
+
+Building requires a Fortran compiler (`gfortran` on Linux/macOS,
+`ifx` on Windows) because part of the numerical work is done by a
+f2py extension.
+
+```bash
+pip install -e .
+```
+
+Runtime dependencies: `numpy`, `scipy`, `endf_parserpy`,
+`matplotlib` (only for the examples).
+
+## 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

endf_userpy-0.1.0a1/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

endf_userpy-0.1.0a1/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

endf_userpy-0.1.0a1/docs/source/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'endf-userpy'
+copyright = '2025, International Atomic Energy Agency (IAEA)'
+author = 'Georg Schnabel, Daniel Lopez Aldama'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

endf_userpy-0.1.0a1/docs/source/index.rst

@@ -0,0 +1,13 @@
+Welcome to endf-userpy documentation
+====================================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   quantities

endf_userpy-0.1.0a1/endf_userpy/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+
+logger = logging.getLogger('endf_userpy')